接口定义命名规范指南

接口定义命名的重要性

写代码的时候，起名字从来不是小事。一个函数叫 getData，另一个叫 fetchUserInfoFromServer，虽然都算“获取数据”，但后者一眼就知道是干啥的。接口作为模块之间沟通的桥梁，命名更得讲究。名字起得好，别人看你的接口文档不用翻注释，调用起来也少出错。

在团队协作中，尤其明显。刚接手项目的小张看到一个叫 process 的接口，心里难免打鼓：这到底处理什么？是订单？用户？还是日志？如果改成 processOrderPayment，疑惑立马少了一大半。

通用命名原则

接口名要能准确表达行为和资源。通常采用“动词 + 名词”的结构，比如 createUser、deleteFile。动词体现操作类型，名词说明目标对象，清晰直接。

避免使用模糊词汇，像 handle、manage、doSomething 这类名字，等于没说。它们就像快递单上写着“物品”而不是“iPhone”，收件人根本不知道来的是什么。

RESTful 风格中的命名习惯

如果是 HTTP 接口，遵循 RESTful 约定会更统一。用 URL 路径表示资源，用请求方法表示动作：

GET    /api/users        # 获取用户列表
POST   /api/users        # 创建新用户
GET    /api/users/123    # 获取 ID 为 123 的用户
PUT    /api/users/123    # 更新用户信息
DELETE /api/users/123    # 删除用户

这种风格下，路径名称用复数名词，全小写，单词间用连字符或驼峰（根据团队规范），不掺动词。动作由 HTTP 方法承担，语义更明确。

不同场景下的命名策略

有些接口不适合纯 REST，比如“用户登录”这种动作性强的操作。这时候可以在路径中加入动词：

POST /api/login
POST /api/logout
POST /api/password/reset

这类接口名直接反映用户行为，比塞进某个资源里更直观。不过动词尽量选通用术语，别自己造词，比如用 reset 别用 clearPwd。

内部服务之间调用的 RPC 接口，命名可以更具体。例如：

getUserProfileById
validateOrderBeforePayment
sendNotificationToUser

这些名字虽然长了点，但在 IDE 里搜索补全很方便，也不会误解用途。

大小写与格式统一

命名格式要一致。主流有三种：小写下划线（get_user_info）、小写连字符（get-user-info）、驼峰式（getUserInfo）。选哪种不重要，关键是整个项目别混着用。

比如前端调用接口时写的是驼峰，后端却返回下划线字段，来回转换容易漏掉字段，调试起来头疼。提前约定好，省去后期麻烦。

避免常见坑

别在名字里加版本号，比如 createUserV2。版本应该体现在 URL 或请求头里，如 /v2/api/users。否则接口越来越多，V3、V4 跟着冒出来，代码库就跟历史书似的。

也别用缩写，除非是广泛认可的，比如 id、url。自己发明的缩写像 updUsr，别人得猜半天是“更新用户”还是“上传用户”。