WebApi闲聊

团队所在的环境中没有太多的规范，导致后台API写的比较混乱，终于自己还是觉得有些东西不能容忍，必须捋一捋这个规范了，既然没有，那就自己写一个吧。

一、规范

1.api路径

url：api/Controller/Action

Controller
使用功能模块命名，例如用户信息相关可以使用UserInfoController，账户相关可以使用AccountController

Action
接口具体做的事情命名。列如登录 login，获取用户信息 getUserInfo

接口路径应严格按照规范编写，便于后继维护和理解。

2.公共参数

request
{
   token:"xxxxxx",
   data:"xxxxxxx",
   device:"xxxxxx"
}

token

用户登录后返回，跟用户信息相关的接口都需要验证token

data

数据，加密后的json字符串

device

请求设备 iOS\Android\PC

response
{
   status:"xxxxxx",
   data:"xxxxxxx",
   message:"xxxxxx"
}

status
服务器返回的请求状态，0失败，1成功

data
服务器返回的数据，加密的json字符串

注：

1. 列表之类的查询如果没有数据，status应为1，data中为空就行，不需要返回没有数据中提示，这对前端来说体验是不好的，前端应该使用自己的处理方式来提示用户没有数据
2. 返回单个数据对象data中应直接返回单个数据对象，而不是一个只有一个对象值的数组
3. 在操作失败其它原因导致status值为0时，必须要有相应的message错误提示信息

message
status不为1时都需要显示的错误新

3.文档

文档是一个非常重要的东西，不仅可以在以后的版本迭代中用来进行测试参照，对于人员的调度时，在沟通上能节省大量的时间和沟通成本，这个成本觉得比你写文档花费的时间要低得多。(我们曾经就因为没有文档，从别的项目组调人过来接手项目，发现结果浪费了很多时间在沟通一些傻瓜式的问题上)

格式：

版本信息

• 公共参数

接口列表

• 接口名字

二、难题

1. 安全问题

• 请求限制

三端通用的情况下，iOS和Android不会那么容易被反编译拿到源码，但是在web端，js的内容都是能直接看到的，所以在安全问题上会比较难受(╯﹏╰)，所以web的js代码必须要混淆加密，server针对有可能被发起破坏操作的接口进行严密的防攻击保护措施，ip、dns、mac地址记录这些举措都是有必要的，并且webapi应分成两个发布，web端使用的需要限制请求域，移动端使用的直接关闭支持跨域功能。

• token问题

使用api的方式必定会需要存在token的问题，因为这是一个用户登录后的获取到身份的凭证，在一定时间的内，用户可以通过token来请求后继许多跟用户信息绑定在一起的操作，在Android或者iOS端都还好，因为本身的系统有一定的保护作用，用户不一定能那么容易获取到这些数据，然而在web端的这些数据，只能是存储在cookies或者localstorage里面，这个时候用户只需要按F12，这些数据就能一览无余了，甚至能让用户才出你后台的业务逻辑，这对后台来说是比较致命的东西，所有我们必须在一定程度上线，或者将这种安全的问题降到最低，web端的js混淆加密，本地存储的数据加密也是比较关键的，这样能在一定程度上防止用户恶意去破坏攻击你的服务器。

2. 迭代问题

后继的版本迭代难免会遇到在新版本中需要将旧版本某些功能变为不可用

• 分版本发布API，API地址不共用列如：

//版本1
http://api.test.com/v1/api/controller/action

//版本2
http://api.test.com/v2/api/controller/action
，
...

这样做的好处是，每个版本的都是独立的，相对来说，每个版本有什么功能，是什么样的，都会比较清晰；但是问题也来了，如果是每个api版本都发了一个地址，那么后继如果是一个v1中的功能，在v5中进行了修改，这个时候v1-v5版本都有用户在使用，为了兼容这些版本，所有的api版本都需要回退、修改、然后重新发布；由此可见，分版本发布api的代价还是很大的，如果让低版本api都直接关闭这些功能，那么问题又来了，当初api分版本发布的意义又何在？（目前我是这么觉得的，如果有什么好的解决办法，请告知哈~）

• 一个版本API兼容多个版本客户端

无论哪个版本的客户端的请求都会进行统一处理，这样所有的功能更改都可以统一处理。客户端这时候应该做好版本更新提示或能通过后台禁用旧版本app引导用户去更新的功能，因为多个客户端版本共用同一版本的API，难免会出现客户端上面的某些功能在当前最新版本的api中被弃用或者需求上的更变，所有客户端配合后台做好禁用旧版本APP引导用户去更新新版本APP还是很有必要的。

闲聊，真的只是闲聊...