1 规范目的与适用范围
为统一公司Java及SpringBoot技术栈项目的代码命名规则，严格对标《阿里巴巴Java开发手册》强制、推荐条款，规范代码编写标准，提升代码可读性、可维护性与可扩展性，降低团队协作沟通成本，保障项目代码质量，规避线上隐患与研发风险，特制定本规范。
本规范适用于公司所有新建、迭代及维护的Java后端项目、SpringBoot单体及微服务项目，覆盖项目编码、代码评审、测试上线、版本维护全生命周期。全体研发人员必须严格遵照执行，若有特殊业务场景需差异化调整，须经技术负责人审批确认，并形成文档备案。
2 通用基础约定（对标阿里规约）
语义化要求：命名优先采用完整标准英文单词，杜绝中文拼音、无意义单字母、随意缩写。仅允许使用行业公认、通用标准的简写，如
id、url、doc、info、dao、xml，禁止自创非通用缩写。大小写与风格约束：Java语言大小写敏感，项目内命名风格必须全局统一，严禁驼峰命名、下划线命名、短横线命名混用。
标识符语法规则：标识符仅允许以字母、下划线、
$开头，后续可跟字母、数字；严禁使用Java关键字、保留字作为标识符。业务代码禁止使用$符号，该符号为Java编译器、内部类专用，避免引发编译冲突与命名混淆。长度约束：命名不宜过长，保证语义清晰的前提下控制长度，避免冗余描述；同时禁止过短命名，除循环临时变量
i、j、k外，不得使用单个字母命名。
3 Java基础元素命名规范
3.1 包名
包名统一采用全小写字母，遵循反向域名命名规则，多级包名使用英文点号分隔，禁止使用下划线、大写字母、特殊字符。
标准包名结构：反向域名 + 公司/部门标识 + 项目名称 + 业务模块 + 子功能层级。
包名层级控制在合理范围，避免过度拆分，通用工具、全局异常、配置类、公共常量等独立划分公共包，与业务代码物理隔离。
package com.company.project.user.service;
package com.company.project.common.exception;
package com.company.project.common.config;
package com.company.project.common.util;3.2 类、接口、枚举及抽象类
统一采用大驼峰命名法（UpperCamelCase），以名词或名词短语命名，清晰体现类的职责、功能与归属，符合阿里规约强制要求。
普通业务实体类：直接使用业务语义命名，如
User、Order、Goods。业务接口：不强制添加I前缀，直接通过名称表达功能，如
UserService、PayStrategy，团队内部保持一致即可。抽象类：统一添加
Abstract前缀，便于快速识别，如AbstractUserService、AbstractBaseController。枚举类：统一添加
Enum后缀，如OrderStatusEnum、GenderEnum，枚举常量采用全大写+下划线分隔。自定义异常类：必须以Exception作为结尾，如
UserNotFoundException、ParamValidateException，区分运行时异常与检查异常，命名体现异常场景。工具类：统一以
Util或Utils为后缀，项目全局统一，如StringUtil、DateUtils。
3.3 方法
采用小驼峰命名法（lowerCamelCase），以动词或动宾短语命名，直观体现方法功能，遵循阿里规约语义化要求。
3.3.1数据查询类动词（核心：区分查询结果形态）
补充规则：
分页查询建议在
query后加Page后缀，如queryUserPage(PageParam param)，一眼识别分页；统计类查询统一用
count作为前缀（优先级最高），特殊场景可补充sum/avg/max/min等前缀，返回值类型严格对应统计结果的数值类型，如countUserByDeptId(Long deptId)，不混用get/count；模糊查询可加
search前缀，如searchUserByName(String keyword)，区分精准 / 模糊查询。
3.3.2数据新增 / 修改类动词（核心：区分操作类型和覆盖范围）
补充规则：
批量新增用
batchInsert，如batchInsertUser(List<UserDTO> list)；批量更新用
batchUpdate，禁止用batchSave（语义模糊）；新增后返回主键的场景，可保持
insert前缀，如insertUserReturnId(UserDTO dto)。
3.3.3数据删除类动词（核心：区分物理删除 / 逻辑删除）
补充规则：
批量删除用
batchDelete/batchRemove，语义与单条保持一致；恢复删除数据用
restore前缀，如restoreUser(Long id)，不混用update/restore。
3.3.4布尔判断类动词（核心：区分判断的语义类型）
补充规则：
所有判断方法名后建议补充判断维度，如
isUserActive而非isActive，避免语义模糊；如用
check作为判断前缀（check更适合 “校验并抛异常”，如checkUserPermission）。
总结
核心原则：动词前缀的选择以 “语义唯一、团队统一” 为核心，比如一旦约定
save为 “新增 + 更新”，全项目必须严格遵守；优先级：
get/find（单条）>list/query（多条 / 分页）、insert/update（明确增改）>save（通用增改）、delete（物理删）>remove（逻辑删）；易混点：
is（状态判断）≠has（存在判断）≠can（能力判断），get（主键查）≠find（非主键查），避免混用。
3.4 变量与方法参数
成员变量、局部变量、方法参数均采用小驼峰命名法，使用名词命名，保证语义清晰。
除循环场景下临时使用
i、j、k外，其余变量禁止使用单个字母命名。禁止使用
m_、_等前缀修饰成员变量，依托现代化IDE提示功能，即可清晰区分变量类型，无需增加冗余标识。实体类属性命名，禁止与数据库关键字冲突，避免SQL解析异常。
private String userName;
private Integer userAge;
public void createUser(String userName, Integer userAge) {
String tempName = userName;
}3.5 常量
被static final修饰的常量，采用全大写字母+下划线分隔，下划线分隔单词，符合阿里规约强制要求。
常量名语义完整，体现常量含义与用途，禁止使用无意义常量名。
全局通用常量归集到公共常量类，业务常量归集到对应业务常量类或枚举类，避免分散定义。
public static final int MAX_PAGE_SIZE = 50;
public static final String DEFAULT_USER_AVATAR = "default.png";
public static final long EXPIRE_SECONDS = 3600L;4 SpringBoot项目专项命名规范（结合阿里微服务与工程规约）
4.1 项目与模块命名
项目名称：统一使用全小写字母+短横线分隔，禁止使用驼峰、下划线、中文及特殊字符。示例：
user-center、order-service、blog-admin、gateway-server。构建文件标识：Maven、Gradle的
artifactId与项目名称完全一致；groupId遵循反向域名规则；版本号采用语义化版本规范，格式为主版本号.次版本号.修订号，如1.0.0、2.1.3，阿里规约不推荐在版本号中添加RELEASE等冗余后缀。多模块项目：子模块命名沿用小写+短横线格式，按职责清晰划分，如
user-center-api、user-center-service、user-center-dao、user-center-sdk。
4.2 分层架构类命名
SpringBoot 项目遵循标准分层架构，各层级类采用固定后缀 + 统一命名规则，明确职责边界，符合阿里分层开发规约，全项目需严格统一执行：
4.2.1 控制层（Controller）
命名规则：
业务领域名 + Controller（大驼峰），无冗余前缀 / 后缀；核心约束：
仅负责请求接收、参数校验、结果返回，禁止包含业务逻辑；
网关、通用拦截器等非业务控制类除外，通用控制类可加 “Common” 前缀（如
CommonExceptionController）；禁止使用 “Action”“Handler” 等替代 “Controller” 后缀；
合规示例：
UserController、OrderController、GoodsController；不合规示例：
UserAction（后缀错误）、UserManagerController（冗余前缀）、OrderApi（无标准后缀）。
4.2.2 业务逻辑层（Service）
接口命名：
业务领域名 + Service（大驼峰），禁止加 “I” 前缀（如IUserService），团队统一即可；实现类命名：
业务领域名 + Service + Impl（大驼峰），“Impl” 为固定后缀；核心约束：
一个业务接口仅对应一个核心实现类，禁止多个 Impl 对应同一接口（特殊场景需加场景后缀，如
UserServiceV2Impl）；通用业务类可加 “Common” 前缀（如
CommonUserService），禁止无意义命名（如BaseService）；
合规示例：
接口：
UserService、OrderService；实现类：
UserServiceImpl、OrderServiceImpl；
不合规示例：
IUserService（冗余 I 前缀）、UserServiceImp（后缀拼写错误）、OrderBusiness（无标准后缀）。
4.2.3 数据访问层
MyBatis/MyBatis-Plus 环境：
命名规则：
业务领域名 + Mapper（大驼峰）；约束：仅负责数据库 CRUD 操作，禁止包含业务逻辑；Mapper 接口与 XML 文件名称完全一致；
示例：
UserMapper、OrderMapper。
JPA 环境：
命名规则：
业务领域名 + Repository（大驼峰）；约束：禁止混用 “Mapper” 和 “Repository” 后缀，同一项目仅选其一；
示例：
UserRepository、OrderRepository。
不合规示例：
UserDao（非标准后缀）、OrderMapperRepository（后缀混用）、UserMapperImpl（无需实现类后缀）。
4.2.4 数据传输对象（DTO/VO/BO）
通用规则：
大驼峰命名，后缀仅允许使用 DTO/VO/BO，禁止自定义（如 TO/PO）或混用大小写（如 UserDto）；
命名格式：
业务领域名 + 功能/场景描述（可选） + 后缀，功能描述需精准体现用途。
各类型具体规则：
约束：禁止 VO/DTO 包含业务逻辑，全项目仅使用一套后缀规则。
总结
分层类命名核心是 “业务领域名 + 固定后缀”，Controller/Service/Mapper/Repository 为层级固定后缀，Impl 仅用于 Service 实现类；
数据传输对象后缀仅允许 DTO/VO/BO，DTO 按操作类型、VO 按展示场景、BO 按业务场景补充描述；
全项目禁止混用后缀（如 Dao/Mapper、Req/DTO）、禁止自定义非标准后缀，确保命名语义唯一、职责清晰。
4.3 接口路径与请求方法
接口设计严格遵循RESTful风格，对标阿里接口开发规范：
接口路径采用全小写字母+短横线分隔，禁止使用驼峰、下划线。
请求方法与业务操作严格对应，禁止全部使用POST请求：GET用于查询、POST用于新增、PUT用于全量更新、PATCH用于局部更新、DELETE用于删除。
接口路径简洁明了，不暴露业务细节与实现逻辑，禁止在路径中使用动词。
4.4 配置相关命名
配置类：统一以
Config为后缀，如MybatisConfig、WebMvcConfig、RedisConfig、ThreadPoolConfig。配置属性类：使用
@ConfigurationProperties注解的类，添加Properties后缀，如MinioProperties、OssProperties、ThreadPoolProperties。配置文件：
主配置文件统一使用
application.yml，优先使用YAML格式，弃用properties格式，提升可读性与层级感，符合阿里推荐规范。多环境配置文件遵循
application-{环境标识}.yml规则，环境标识使用dev、test、pre、prod，对应开发、测试、预发、生产环境。配置项key采用全小写字母+短横线分隔，可与代码小驼峰格式自动映射，禁止使用大写与下划线。
spring:
datasource:
url: jdbc:mysql://localhost:3306/test
username: root
password: root
redis:
host: localhost
port: 6379
mybatis:
mapper-locations: classpath:mapper/*.xml4.5 Bean与组件命名
使用
@Service、@Component、@Repository、@Controller等注解声明组件时，无需手动指定value属性，Spring框架默认以类名首字母小写作为Bean名称，如userService、userMapper，避免手动指定引发命名冲突。手动注册Bean时，配置方法采用小驼峰命名，方法名即为Bean名称，一个配置类中避免注册多个同名Bean。
@Configuration
public class ThreadPoolConfig {
@Bean
public ExecutorService threadPoolTaskExecutor() {
// 线程池初始化逻辑
}
}4.6 定时任务与异步方法
定时任务方法：采用小驼峰命名，统一以
Task结尾，如userCleanTask()、orderTimeoutTask()，定时任务类可添加Schedule、Task后缀。异步方法：配合
@Async注解使用，统一添加Async后缀，如sendMessageAsync()、saveLogAsync()，方便识别与维护。
5 项目文件及目录规范（阿里工程规约适配）
源码目录：业务代码固定存放于
src/main/java，配置文件、静态资源、Mapper XML等资源文件存放于src/main/resources，测试代码存放于src/test/java。静态资源目录：
resources/static用于存放前端静态资源，resources/templates用于存放服务端模板页面，无前后端不分离场景可精简。MyBatis映射文件：统一归集至
resources/mapper目录，文件名与对应Mapper接口完全一致，如UserMapper.xml，禁止随意存放、命名混乱。日志文件：禁止存放于项目源码目录，通过配置统一输出至服务器独立日志目录，日志文件名使用
项目名-服务名-日期.log格式，按天滚动，符合阿里日志规范。测试代码：
src/test/java目录下的包结构，需与主业务代码完全一致；测试类统一以Test结尾，如UserControllerTest、UserServiceTest，单元测试、集成测试分类管理。
6 强制禁止项与常见违规说明（对标阿里规约强制条款）
严禁拼音命名：禁止使用中文拼音、拼音缩写命名，如
YongHu、DingDan、yhgl，所有命名必须使用标准英文。严禁魔法值：禁止在代码中硬编码固定数值、状态码、字符串等魔法值，所有固定常量必须通过常量类或枚举类统一维护，如禁止
if(status == 1)，应改用if(OrderStatusEnum.PENDING.getCode().equals(status))。严禁命名风格混用：项目内代码、接口路径、配置文件、数据库相关命名，不得同时出现小驼峰、下划线、短横线混用的情况。
严禁无意义命名：杜绝
temp、string、map、list等无法表达业务含义的命名，方法、变量命名必须体现用途。严禁冗余与过度封装：禁止随意创建Service、DTO、工具类，避免层级混乱、类名冗长；禁止重复定义常量、枚举。
严禁遗留无效代码：测试代码、临时调试代码、废弃注释、无效代码，在代码提测、上线前必须清理，不允许带入生产环境。