接口文档设计

接口文档设计分为两部分：

1、对外接口设计规范，

1. 提供完整的接口文档
2. 提供接口调用的代码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)		可空

2、内部接口规范，

1. 发布façade接口jar包，包含了API、request、response
2. 提供接口对应的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

 

基于HTTP标准协议的API接口设计规范构思

• node.js
 
•  python
 
• javascript
 
• golang

 

Prasanta 2016年12月19日发布

• 赞  |   0收藏  |  3
• 1.7k 次浏览

开发规范

1. 版本控制git

2. 开发流程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	删除

数据

1. 请求支持form-date,json,x-www-form-urlencode

2. 返回格式统一为json

3. 一个请求对应一个serializer

错误

1. 错误信息包含在返回内容里

2. 不一样的错误对应不一样的错误信息代码

3. http错误码按照标准用法使用

认证

1. jwt

2. token

3. oauth2

权限

1. 以中间件形式做为权限鉴别插件，根据http请求格式直接判断权限

2. 用户登陆成功时，将用户信息与权限信息缓存保证效率

日志

1. 日志以中间件形式提供

2. 根据业务需求氛围入库日志与普通日志

文档(待完善)

根据上面的接口格式写文档

{
  "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层接口设计的基本原则和规范要求。

整体规范

1. 接口中方法的返回不能为void，至少也要通知调用者，操做是否成功
2. 接上条，凡是返回操做是否成功的方法，返回类型要设置为int而不是boolean
3. 方法名只能使用英文，尽可能简单易懂，驼峰规则，首字母小写，不得含有数字
4. 方法名最好使用动宾结构。
5. 接口中全部方法都必须写注释
6. 接口中全部方法都必须是public的
7. 每一个方法的位置应当是明确的，不要将不属于某接口的方法放入该接口中，也不要写功能重复的方法

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();