命名建议（Java）

数据库

表名命名

• 要求使用下划线_分隔

• 前缀说明（视需求而定）

  • sys_：管理端数据表前缀，例如：系统配置表sys_config；
  • tb_：功能业务相关表，记录业务数据，也可以使用其他前缀，例如：业务中台bme_；

  但单体应用或者系统体量较小的情况下不建议使用前缀。

注：及其不推荐使用拼音缩写作为表名，建议使用英文单词！

字段命名

• 要求使用下划线_分隔
• 建议使用英文单词

例如：

​ 正确示范：user_name

​ 错误示范：yhm

开发语言

实体类

项目中应只出现三种后缀实体类，DTO、VO、PO。

存放位置

• 实体类应都存在于model包中，每一种类型的实体类都应该新建一个自己的包，例如：DTO需要新建一个dto的包存放。

• 在各类型的实体类包的下一层还应根据内容再创建一个包进行存放，例如：新增用户接口请求参数模型实体类的存放路径应为：model/dto/user/CreateUserDTO，其中user则是对象内容新增的一层归纳。

命名规范

• DTO：用于接口请求参数实体类定义，以及各服务或各方法之间出现多个入参时需要构造的实体类，例如：新建用户信息接口的请求参数实体类命名为：CreateUserDTO。

• VO：用于接口响应参数实体类定义，以及各服务或各方法之间出现多个返回参数时需要构造的实体类，例如：查询用户详细信息接口的响应参数实体类命名为：QueryUserDetailInfoVO。

• PO：用于数据库实体类定义，以及涉及到数据库操作的映射字段实体类的定义，例如：数据库表名为：sys_user，则实体类命名为UserPO，分页查询用户信息列表时从数据库返回的映射实体类命名为：PaginatedQueryUserInfoListPO。

方法名命名

方法命名采用蛇形命名法，且首字母小写，命名规则原则为{action}{object}{data range}{condition}，相关说明如下：

• action：动作，即该方法所要执行的动作，推荐的动作如下：
  • create：新建
  • update：编辑
  • delete：删除
  • query：查询
  • paginatedQuery：分页查询
• object：对什么对象执行动作，通常是数据库实体或者抽象出来的对象，例如：用户（user）。
• data range：数据范围，可选项，常用于查询类方法的命名，可选的数据范围如下：
  • detailInfo：详细信息
  • infoList：信息列表
• condition：执行操作的条件，可选项，例如：byUnCode：根据唯一标识unCode

举例，以在接口定义层service中的接口方法命名为例（UserService）：

• 创建用户方法：Boolean createUser(CreateUserDTO createUserDTO)
• 更新用户方法：Boolean updateUser(UpdateUserDTO updateUserDTO)
• 删除用户方法：Boolean deleteUser(String unCode)或者Boolean deleteUser(DeleteUserDTO deleteUserDTO)
• 查询用户详细信息：QueryUserDetailInfoVO queryUserDetailInfo(String unCode)
• 分页查询用户信息列表：PaginatedQueryUserInfoListVO paginatedQueryUserInfoList(Page page)

变量名命名

变量名的命名需要做到名副其实，尽力做到见名知意，当需要注释来对变量名进行补充说明时，则需要考虑是否可以优化，针对不同数据类型的变量命名建议如下：

布尔值类型

布尔类型变量命名需要尽量使用正逻辑命名，例如：is、exist等，避免反逻辑命名，例如：not。

注意：极特殊情况下，变量命名isXxxx可以会在序列化时导致错误。

正确示范：isSuccess、isFail；

错误示范：flag、notSuccess。

字符串类型

字符串类型变量命名可以考虑使用Str结尾。

数值类型

数值型变量命名时需要明确对象，例如：请求重试次数变量可以命名为timeOfRequestRetry

数组类型

数组类型变量命名可以考虑使用Arry结尾。

列表类型

列表类型变量命名可以考虑使用List结尾。

API（参考Restful API设计规范）

参考文章：RESTful API 设计规范 - 掘金 (juejin.cn)

域名

• 子域名：api.example.com/*
• 主域名：example.com/api/*

版本控制

为方便后续的功能迭代升级，api可以引入版本控制，实现版本控制的方式有很多种，这里介绍一种，api的前缀可如下命名：api.example.com/v1/*，其中v1表示第一版本的接口，后续如果更新至第二版的接口时，即可将api更换为api.example.com/v2/*，如此即可保证两个版本的接口同时在线，迭代升级时不会影响到其他现有的业务。

路径

关于api路径命名，需要遵循如下几个约定：

• 命名必须全部小写
• 资源（resource）的命名必须是名词，并且必须是复数形式；
• 如果要使用连字符，建议使用"-"而不是"_"，"_"字符可能会在某些浏览器或屏幕中被部分遮挡或完全隐藏

以上的约定与Restful API的设计规范一致，如果仍要与该设计规范保持一致，则可以参照以下方式命名api：

HTTP动词

对于如何操作资源，有相应的HTTP动词对应，常见的动词有如下五个（括号里表示SQL对应的命令）：

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）
• DELETE（DELETE）：从服务器删除资源

示例：

HTTP动词	路径	表述
GET	/zoos	获取所有动物园信息
POST	/zoos	新建一个动物园
GET	/zoos/{id}	获取指定动物园的信息
PUT	/zoos/{id}	更新指定动物园的信息（前端提供该动物园的全部信息）
PATCH	/zoos/{id}	更新某个指定动物园的信息（提供该动物园改动部分的信息）
DELETE	/zoos/{id}	删除某个动物园
GET	/zoos/{id}/animals	获取某个动物园里面的所有动物信息

其中{id}表示唯一标识符，是一个变量。

如果接口设计规范不再遵循Restful API的设计规范时，例如：接口允许的请求方式允许POST或者POST、GET两种，那么可参考一下的命名规范：

• 只允许POST请求

  HTTP动词	路径	表述
  POST	/zoos/query	获取所有动物园信息
  POST	/zoos/paginated/query	分页获取所有动物园信息
  POST	/zoos/create	新建一个动物园
  POST	/zoos/update	修改一个动物园的信息
  POST	/zoos/delete	删除一个动物园
  POST	/zoo-animal-rel/create	新建将某只动物迁入某个动物园中

• 只允许POST、GET请求

  HTTP动词	路径	表述
  GET	/zoos/query	获取所有动物园信息
  GET	/zoos/paginated/query	分页获取所有动物园信息
  POST	/zoos/create	新建一个动物园
  POST	/zoos/update	修改一个动物园的信息
  POST	/zoos/delete	删除一个动物园
  POST	/zoo-animal-rel/create	新建将某只动物迁入某个动物园中