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

news2024/10/26 17:19:17

每天都在写很多接口，有的是有设计的接口，有的是无设计的接口。如果接口没有进行设计，也没有设计文档后期将很难扩展和维护。那么怎么简单定义一个简单而标准的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

请求参数示例：

请求参数(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