【升华】一个简单而标准的接口定义格式

一、前言

       每天都在写很多接口，有的是有设计的接口，有的是无设计的接口。如果接口没有进行设计，也没有设计文档后期将很难扩展和维护。那么怎么简单定义一个简单而标准的Java的接口呢。下面给出格式。

二、JAVA接口设计文档

一个接口的定义一般包括：接口的方式，接口的地址，接口的作用，接口的调用实时性，接口的请求方式，和接口的请求参数，接口的返回参数等信息

■ 接口方式

Restful

■ 接口地址

地址: [IP_MNP]/user/register

■ 描    述

会员注册

■ 同步方式

实时

■ 请求方式

POST

■ 请求参数

字段	类型	名称	必须	备注
token	String	接口访问access_token	Yes
phone	String	会员手机号	Yes
dialCode	String	手机区号	Yes
idType	Integer	证件类型	Yes	0:身份证 1:护照 2:港澳通行证 3:台胞证
idNumber	String	证件号	Yes
validEndDate	Date	证件失效日期	No	除身份证外必填
sex	String	会员性别	Yes	"1":男 "2":女
realName	String	会员真实姓名	Yes
enRealName	String	会员英文姓名	No
nationality	String	国籍代码	Yes	参考附录国家列表，欧盟国籍禁止注册
birthday	Date	会员出生日期	Yes	身份证需根据身份证自动获取生日，
storeOuCode	String	门店编码	Yes	取会员注册门店编码小程序
createTime	DateTime	注册时间	No	yyyy-MM-dd hh:mm:ss
isReceiveMsg	Integer	手机短信消息开关	Yes	0:关、1:开
isReceiveEmail	Integer	电子邮件消息开发	Yes	0:关、1:开
isReceivePost	Integer	微信即时消息开关	Yes	0:关、1:开
ctgChannel	String	渠道	No	传值，按照等级映射业务执行， 不传或空值，则按照正常注册会员执行
ctgLevelNo	String	等级	No	会员等级 1:普通会员 2:金卡会员 3:白金会员 4:钻石会员
cdfLevelNo	String	映射等级	No	0001：普通会员 0002：银卡会员 0003：金卡会员 0004：铂金会员 0005：钻石会员
ctgLevelList	List	渠道会员等级列表	No	参考表3.1.2

表3.1.1

字段	类型	名称	必须	备注
ctgChannel	String	渠道	Yes
ctgChannelName	String	渠道名称	Yes
ctgLevelNo	String	渠道等级编码	Yes
ctgLevelName	String	渠道等级名称	Yes

请求参数示例：

请求参数(x-wwww-form-urlencoded)示例:

token = "187402837510472310" jsonData = { "phone": "13811***082", "idType": 0, "idNumber": "698382989392938", "dialCode": "86", ... "ctgChannel": "CtgTour", "ctgLevelNo": "1", "cdfLevelNo": "0002", "ctgLevelList": [ {   "ctgChannel": "CtgTour",   "ctgChannelName": "旅行",   "ctgLevelNo": "3",       "ctgLevelName": "钻石"     },{   "ctgChannel": "CtgHotel",   "ctgChannelName": "酒店",   "ctgLevelNo": "3",       "ctgLevelName": "钻石"        }     ] }

 接口响应结果：

■ 响应结果

字段	类型	名称	备注
result	Boolean	请求响应结果	true/false
resultCode	String	错误码
currentTime	DateTime	请求响应时间	忽略返回值
msg	String	请求响应信息	result为true时,msg为”success”; result为false时,msg为失败的的详细信息
data	Object		null

响应接口示例：

■ 请求成功返回结果示例

{ "status": 0, "info": null, "result": "success", "data": null, "currentTime": "2018-12-17 17:52:32" }

■ 请求异常，返回结果示例

{ "status": -1, "errorCode": 1000, "info": "系统异常, 参数错误!", "data": null, "current_time": "2020-07-23 12:00:03" }