一种简单且通用的后端api接口相关命名规范

男娘i 2023-09-23 17:01 32阅读 0赞

我在项目中比较重视api接口的命名规范，好的命名不仅能方便前后端联调，而且代码维护也是很方便的。  
不幸的是，很多工作几年的老程序员在命名这个事情上也是一塌糊涂。想整理一个规范出来，能够方便开发人员去落实，这个规范一定要简单，不同能力水平的开发人员都能很容易理解和使用。

**一、痛点**  
在命名这个问题上，经常遇到如下这些问题：

1.  接口地址不规范（项目上我们使用restful风格，但是很多程序员连restful是什么都不清楚）
2.  方法名称不规范，包括controller和service的方法
3.  参数定义不规范，经常会写出非常长的参数列表
4.  请求类和返回类名定义不规范

我们这个规范就是围绕上面这些问题，并且给出相应的解决方案。

**二、规范定义**

1.  接口定义  
    接口定义必须符合restful规范，因为我们这个命名规范是非常依赖请求地址的合理性的  
    比如，我有一个用户管理的需求，有下面几个功能  
    用户列表：GET /users  
    创建用户：POST /users  
    修改用户：PUT /users/\{id\}  
    删除用户：DELETE /users/\{id\}  
    我们第一步就是要像上面这样先定义好每个接口的请求地址，一般我都会先设计好请求地址，实现交给开发自己去做。在做接口设计的时候，其实也是需求分析的过程，开发按照已经设计好的接口清单去开发，能够被规范在一个框架内，不至于跑偏。
2.  controller和service命名  
    一般情况下，我们会按照系统有用的功能模块进行controller的划分，通常都是一个模块一个controller。比如系统有用户管理、报表管理，那么controller就会这么定义：  
    用户管理：UserController  
    报表管理：ReportController

一个controller至少需要一个主的service，比如：  
用户管理：UserService  
报表管理：ReportService  
controller中一般只调用主service的入口方法，主service可以依赖其他service。

1.  方法命名  
    这部分是规范的关键，命名这个事情真的是考验英文水平的。所以为了消除这个差异，让不同水平的开发都能定义出相对合理的命名，我们最终的做法就是按照接口的请求地址进行转换，比如：  
    用户列表：GET /users -> listUser  
    创建用户：POST /users -> createUser  
    修改用户：PUT /users/\{id\} -> updateUser  
    删除用户：DELETE /users/\{id\} -> deleteUser

转换的规则就是请求的Method + RequestMapping，当然这里不是直接拼接，还是要做一些处理的，Method部分的处理：  
GET -> list/get/find  
POST -> create/add  
PUT -> update/modify  
DELETE -> delete/remove/drop

RequestMaping部分，直接转成驼峰写法即可，比如：  
用户操作日志：GET /users/opr\_log -> listUserOprLogs  
删除某用户拥有的角色：DELETE /users/\{id\}/roles -> deleteUserRoles或deleteUserRolesById

1.  请求类和返回类定义  
    这部分更简单：  
    请求类：方法名+Request  
    返回类：方法名+Response

request/response是我们项目的一个规范，有些人喜欢params/data，或者阿里规范的dto/vo等都可以，按照自己的项目要求来即可。

举例：  
用户列表：ListUserRequest/ListUserResponse  
创建用户：CreateUserRequest/CreateUserResponse  
修改用户：UpdateUserRequest/UpdateUserResponse

这个规则可能会有些争议，一是太啰嗦，二是复用性不太好。比如创建和修改返回的都是用户对象（UserPojo），却要定义两个对象。当然这里用一个也没问题，定义两个的话也可以通过继承UserPojo避免定义重复的字段。  
但是他的好处也是显而易见的，那就是类的命名见名知意，不用费脑筋。