接口文档设计分为两部分：
一、对外接口设计规范，
- 提供完整的接口文档
- 提供接口调用的代码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(); |