接口文档设计分为两部分:
一、对外接口设计规范,
- 提供完整的接口文档
- 提供接口调用的代码Demo
示例如下:
请求的基本参数
参数 | 参数名称 | 类型 (长度范围) | 参数说明 | 是否可为空 | 样例 |
基本参数 | |||||
| 接口名称 | String(64) |
| 不可空 | send_goods_confirm_by_platform |
| 合作者身份ID | String(16) |
| 可空 | 2088001159940003 |
| 参数编码字符集 | String(10) |
| 不可空 | GBK |
| 签名 | String(64) |
| 不可空 | e8qdwl9caset5zugii2r7q0k8ikopxor |
| 签名方式 | String(10) |
| 不可空 | MD5 |
| 页面跳转同步返回页面路径 | String(1000) |
| 可空 |
|
| 备注 | String(1000) |
| 可空 |
|
同步返回时,需要的基本参数
参数 | 参数名称 | 类型 (长度范围) | 参数说明 | 是否可为空 | 样例 |
|
基本参数 |
| |||||
| 成功标识 | String(1) |
| 不可空 | T |
|
| 合作者身份ID | String(16) |
| 可空 | 2088001159940003 |
|
| 参数编码字符集 | String(10) |
| 不可空 | GBK |
|
| 签名 | String(64) |
| 不可空 | e8qdwl9caset5zugii2r7q0k8ikopxor |
|
| 签名方式 | String(10) |
| 不可空 | MD5 |
|
| 返回错误码 | String(30) |
| 可空 | PARTNER_ID_NOT_EXIST |
|
| 返回错误原因 | String(200) |
| 可空 | 合作方Id不存在 |
|
| 备注 | String(1000) |
| 可空 |
|
|
二、内部接口规范,
- 发布façade接口jar包,包含了API、request、response
- 提供接口对应的response返回码说明,及接口所需属性枚举常量定义
示例如下:
接口名称: | XXXXXXXXXXXXXXX | |||
请求参数 | 属性 | 描述 | 是否必填 | 字段类型 |
|
|
| Y | String(32) |
|
| Y | String(32) | |
|
| Y | String(32) | |
|
| Y | String(32) | |
|
| Y | String(32) | |
|
| Y | Money | |
|
| N | String(32) | |
|
| N | String(32) | |
|
| N | String(2) | |
|
| N | String(32) | |
|
| N | String(32) | |
|
| N | String(64) | |
|
| N | String(256) | |
|
| N | String(12) | |
|
| N | String(64) | |
|
| N | String(64) | |
|
| N | String(1) | |
|
|
| String(1) | |
|
| N | String(256) | |
|
| N | String(2000) | |
|
|
|
|
|
返回参数 | 属性 | 描述 | 是否必填 | 字段类型 |
|
| 返回码 | Y | String |
| 返回信息 | N | String | |
| 扩展信息 | N | String |
开发规范
-
版本控制git
-
开发流程git flow
接口
请求方式 | url | 动作 | 中文说明 |
---|---|---|---|
GET | /resources/ | list | 列表 |
POST | /resources/ | create | 创建 |
GET | /resources/:id | retrieve | 详细 |
PUT | /resources/:id | update | 更新 |
PATCH | /resources/:id | partial_update | 部分更新 |
DELETE | /resources/:id | destroy | 删除 |
数据
-
请求支持form-date,json,x-www-form-urlencode
-
返回格式统一为json
-
一个请求对应一个serializer
错误
-
错误信息包含在返回内容里
-
不同的错误对应不同的错误信息代码
-
http错误码按照标准用法使用
认证
-
jwt
-
token
-
oauth2
权限
-
以中间件形式作为权限鉴别插件,根据http请求格式直接判断权限
-
用户登录成功时,将用户信息与权限信息缓存保证效率
日志
-
日志以中间件形式提供
-
根据业务需求氛围入库日志与普通日志
文档(待完善)
根据上面的接口格式写文档
{
"resources": {
"list": {
"params": {},
"response": {}
},
"create": { "request": {}, "response": {} }, "retrieve": { "response": {} }, "update": { "request": {}, "response": {} }, "partial_update": { "request": {}, "response": {} }, "destroy": {} } }
测试
业务所需接口测试覆盖率100%
部署
-
docker
-
docker-compose
-
docker-machine
-
docker-swarm
服务器资源监控
接口设计规范
浙江大学电子服务研究中心
首先,在阅读本文档前请务必确认您已经对面向对象的基本概念有所了解。
根据目前实验室所使用的系统架构,制定本文档,主要阐述一些service层和DAO层接口设计的基本原则和规范要求。
总体规范
- 接口中方法的返回不能为void,至少也要通知调用者,操作是否成功
- 接上条,凡是返回操作是否成功的方法,返回类型要设置为int而不是boolean
- 方法名只能使用英文,尽量简单易懂,驼峰规则,首字母小写,不得含有数字
- 方法名最好使用动宾结构。
- 接口中所有方法都必须写注释
- 接口中所有方法都必须是public的
- 每个方法的位置应当是明确的,不要将不属于某接口的方法放入该接口中,也不要写功能重复的方法
service层接口规范
service层是每个模块逻辑处理的位置,一个service对应一个action和若干个DAO,service中每一个方法都来自页面功能的需求,所有service层的接口都必须继承自BaseService,所有方法都应当以BaseForm(或其子类)的对象作为参数,根据需要可以添加PageInfo的对象,其他参数一般不要添加。
以下方法是在BaseService中已经声明的:
/** * 添加一条新数据 * @return 消息编码 */ public int addData(BaseForm thisForm); |
/** * 编辑一条数据 * @return 消息编码 */ public int editData(BaseForm thisForm); |
/** * 删除一条或多条数据 * @return 消息编码 */ public int removeData(BaseForm thisForm); |
/** * 返回一条数据,并用于页面展示 * @return BaseForm */ public BaseForm showData(BaseForm baseForm); |
实例:
/** * 分页显示照片 */ public List<DataPhoto> getDataPhotoByConditionsInPage(PageInfo pageInfo, DataPhotoForm dataPhotoForm);
/** * 获取某个相册下的所有照片 */ public List<DataPhoto> getAllDataPhoto(DataPhotoForm dataPhotoForm);
/** * 删除某个相册下的所有照片 */ public int removeDataPhotoByGroup (DataPhotoForm dataPhotoForm);
/** * 获取某相册相片及回复 */ public Map<Integer, List<DataPhotoReply>> getDataPhotoAndReplyByGroup (DataPhotoForm dataPhotoForm); |
DAO层接口规范
DAO层的作用是操作数据库,每一个接口对应数据库中的一个表,可以被多个service调用。DAO层接口中所有的方法都与数据库的“增删改查”相联系。所有的DAO层接口都必须继承自BaseDAO
以下是BaseDAO中已经声明的方法:
/** * 将一个Model添加进数据库 */ public int insertModel(BaseModel model); |
/** * 更新Model */ public int updateModel(BaseModel model); |
/** * 删除一条或多条数据 */ public int deleteModels(int[] ids); |
实例:
/** * 分页显示照片 */ public List<DataPhoto> getDataPhotoByConditionsInPage(PageInfo pageInfo, DataPhoto dataPhoto); |
/** * 获取某个相册下的所有照片 */ public List<DataPhoto> getAllDataPhotoByGroup(DataPhoto dataPhoto); |
/** * 删除某个相册下的所有照片 */ public int deleteDataPhotoByGroup(DataPhoto dataPhoto); |
/** * 获取相片及其回复 */ public Map<Integer, List<DataPhotoReply>> getDataPhotoAndReplyByGroup (DataPhoto dataPhoto); |
/** * 插入一条数据后,立刻返回该条数据id */ public int getPhotoIdRightNow(); |