接口文档规范的一些总结

写接口文档似乎是一件不是那么硬核的技术，但是其实对于提升团队效率和项目的交接等会发挥比较重要的作用。本人近期总结了一些接口文档的规范。

参考文章如下：https://www.jianshu.com/p/dc0bc8613762

https://blog.csdn.net/fly1056601582/article/details/65935938

总结如下：

接口规范：
RESTful api规范
url:不含大写，uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开

版本号：
整数和复数
https://api.jupiter.com/v1/
https://api.jupiter.com/v1.1/

资源集合：
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

https://api.jupiter.com/v1.1/zoo
https://api.jupiter.com/v1.1/animals
https://api.jupiter.com/v1.1/employees

入参：

返回参数结构：
三部分：
状态码+状态码描述+数据（单数据或者集合）
错误必须给出错误信息
{
status:0,
data:{
}||[],
msg:’’
}

数组
{
status:0,
data:[
],
msg:’’
}

/*********************************************/
命名规约
所有编程相关命名均不能以下划线或 美元符号开始，也不能以下划线或美元符号结束。
所有编程相关的命名严谨使用拼音与英文混合的方式，更不允许直接使用中文的方式。 
*说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用

类名使用UpperCameCase风格，必须遵从驼峰形式，但一下情形例外：（领域模型的相关命名）DO／DTO／VO／DAO等。 
*MarcoPolo／UserDO／XmlService／TcpUdpDeal／TaPromotion

方法名、参数名、成员变量、局部变量都统一使用lowerCameCase风格，必须遵从驼峰形式。 
*localValue／getHttpMessage／inputUserId

常量名称全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
抽象类命名使用Abstact或Base开头；异常类命名使用Exception结尾，测试类命名以它要测试的类的名称开始，以Test结尾。
中括号是数组类型的一部分，数组定义如下：String[]args;

POJO类中的任何布尔类型的变量，都不要加is，否则部分架构解析会引起序列化错误。

包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如有复数含义，类名可以使用复数形式。
杜绝完全不规范的缩写，避免望文不知义。

如果使用到了设计模式，建议在类名中体现出具体模式。

接口类中的方法和属性不要加任何修饰符号，保证代码的简洁性，并加上有效的javadoc注释。尽量不要在接口里定义常量，如果一定要定义变量，肯定与接口方法相关，并且是整个应用的基础变量。 
*接口方法签名：void f(); 接口基础常量表示：String COMPANY=”alibaba”。

接口和实现类的命名有两套规则： 
1 对于service 和dao类，基于soa的理念，暴露出来的服务一定是接口，内部的视线类用Imple的后缀于接口区别。 
2 如果是形容能力的接口名称，取对应的形容词做接口名。（通常是-able的形式

后台命名规范：
server／dao层方法命名规约 
1获取单个对象的方法用get做前缀。 
2获取多个对象的方法用list做前缀。 
3获区统计值的方法用count做前缀。 
4插入的方法用save做前缀。 
5删除的方法用remove做前缀。 
6修改的方法用update做前缀。