算是前后端合作默认工作事项,主要遇到新团队磨合过程中问题点,所以总结一下。所有的默认事项都是为了统一和规范,降低沟通、理解和开发成本。
确定常用英文单词
常用的比如:查query,增/新建create(或者add),改/编辑update(或者edit),删delete,页码pageNum,每页条数pageSize,总数total等。
一个意思只用一个单词,比如修改可以用update也可以用edit,但是确定单词后只使用一个,不再使用另一个
接口:最好使用RESTful风格API,接口中不出现动词。
例:用户相关接口。url都以/users开头
查:GET /users/{id}(单个),/users?pageSize=10&pageNum=1(列表)
增:POST /users data: { name: "Lee" , age: 30 },数据在body里
改:PUT /users/{id} data: { name: "Lee" , age: 30 },数据在body里
删:DELETE /users/{id}
批量操作都用POST:
批量改:/users Body: { "update": { ids: [ "1", "2", "3" ], "status": 1 } }
批量增:/users Body: { "create": [{ name: "Amy", age: 35}, { name: "Joe", age: 40 }] }
批量删:/users Body: { "delete": { ids: [ "1", "2", "3" ] } }
表示同一意义的字段名不论在什么接口中单词都保持一致
如订单号orderCode,不论在查询用户订单接口的返回值中,还是在退货单接口表示关联的订单号,都应该用orderCode,不要一处用code,一处又是oCode,一处又变成orderCode。
接口返回值格式统一,不同状态码表示不同意义
常见接口返回值分为三部分:状态码int,数据,消息string。
例如:{ code: 200, data: { id: "11", .... }, msg: "success" }
状态码表成功可以用0或者200或者约定好的整数,其他如登录过期、账号或密码错误、暂无权限等都应有相应的状态码。
不同状态码,有些是需要将消息告知用户的,如“登录过期,请重新登录”,有些不需要将详细信息展示给用户,可展示为“系统错误,请联系运维/管理员”