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

老马的编程笔记

已于 2022-11-29 17:38:00 修改

阅读量5.5k

点赞数 2

分类专栏： Java 文章标签： java 开发语言

于 2022-11-29 17:33:22 首次发布

本文链接：https://blog.csdn.net/qq_23365135/article/details/128101229

版权

Java 专栏收录该内容

11 篇文章

订阅专栏

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

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

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

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

二、规范定义

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

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

方法命名
这部分是规范的关键，命名这个事情真的是考验英文水平的。所以为了消除这个差异，让不同水平的开发都能定义出相对合理的命名，我们最终的做法就是按照接口的请求地址进行转换，比如：
用户列表：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