Java程序编码规范

Java程序编码规范1.总则1.1目的为统一Java代码编写标准，提高代码的可读性、可维护性、可扩展性和健壮性，减少代码冗余与潜在bug，规范团队开发流程，降低协作成本，确保项目代码质量的一致性，特制定本规范。本规范适用于所有Java项目开发、维护及重构过程，所有参与Java开发的人员必须严格遵守。1.2适用范围本规范适用于Java语言开发的所有项目（包括后端服务、工具类、桌面应用等），涵盖代码编写、注释、格式、命名、异常处理、安全等各个环节，同时适用于新开发代码、现有代码重构及代码评审过程。1.3核心原则可读性优先：代码是写给人看的，其次才是机器执行，确保他人能快速理解代码逻辑。一致性：命名、格式、注释等遵循统一标准，不随意变通。简洁性：避免冗余代码，用最简洁的方式实现业务逻辑，不写无用代码。健壮性：考虑异常场景，合理处理异常，避免程序崩溃，同时兼顾性能。可维护性：代码结构清晰，模块划分合理，便于后续修改和扩展。2.命名规范2.1通用命名原则命名需清晰、准确，能直接反映对象的用途、含义或功能，避免模糊、歧义的命名；禁止使用拼音（特殊业务场景除外，如地名、人名，需标注说明），禁止使用无意义的字符（如a、b、c、temp1、test等）；严格区分大小写，遵循Java大小写规范，避免大小写混淆导致的错误。2.2类命名采用“帕斯卡命名法（PascalCase）”，即首字母大写，后续每个单词首字母均大写，如：UserController、OrderService、StringUtils。类名需体现类的用途，名词或名词短语，避免动词开头，如：正确命名User、OrderDao，错误命名AddUser、QueryOrder。特殊类命名约定：控制器类：以“Controller”结尾，如UserController、ProductController。服务类：以“Service”结尾，如UserService、OrderService；服务实现类以“ServiceImpl”结尾，如UserServiceImpl。数据访问类（DAO）：以“Dao”结尾，如UserDao、OrderDao；DAO实现类以“DaoImpl”结尾。实体类（POJO/Entity）：直接使用业务名词，如User、Order、Product，无需额外后缀（特殊场景可加“Entity”，如UserEntity）。工具类：以“Utils”结尾，如StringUtils、DateUtils，工具类需设计为单例或全静态方法。异常类：以“Exception”结尾，如BusinessException、ParamException。2.3方法命名采用“驼峰命名法（camelCase）”，即首字母小写，后续每个单词首字母大写，如：getUserById、addOrder、updateProduct。方法名需体现方法的功能，以动词开头，搭配名词或名词短语，清晰表达方法的操作意图，如：查询类：get（单个）、list（列表）、find（查询，灵活场景）、select（数据库查询），如getUserById、listOrderByStatus。新增类：add、insert，如addUser、insertOrder。修改类：update、edit，如updateUserInfo、editOrderStatus。删除类：delete、remove，如deleteUserById、removeOrder。判断类：is、has、exists，返回值为boolean，如isUserExist、hasPermission。工具类方法：体现具体功能，如StringUtils.isEmpty、DateUtils.formatDate。禁止方法名过于简单，如method1、doSomething，需精准描述功能。2.4变量命名采用“驼峰命名法（camelCase）”，首字母小写，后续每个单词首字母大写，如：userId、orderNo、productName。变量名需清晰反映变量的含义和用途，避免模糊命名，如：正确命名userName，错误命名name（需结合上下文，若上下文明确为用户场景，可简化，但优先清晰）。局部变量：尽量简洁但不模糊，如在循环中使用i、j（仅用于简单循环索引），复杂场景需使用有意义的名称，如orderId、productCount。成员变量：禁止使用单字符命名，除非是临时循环变量（i、j、k等），且循环范围仅限几行代码。常量命名：采用“全大写+下划线分隔”，如：MAX_PAGE_SIZE、USER_STATUS_ACTIVE、DEFAULT_TIMEOUT，常量需定义在类的顶部，使用final修饰。枚举命名：枚举类名遵循类命名规范（PascalCase），枚举值遵循常量命名规范（全大写+下划线），如：2.5包命名采用“全小写+点分隔”，遵循“反向域名+项目名+模块名”的格式，如：ject.controller、ject.service。包名需体现模块划分，常见包结构约定：controller：存放控制器类，处理请求入口。service：存放服务接口类。service.impl：存放服务接口实现类。dao/mapper：存放数据访问接口（MyBatis场景用mapper）。entity/pojo：存放实体类。util：存放工具类。exception：存放自定义异常类。config：存放配置类。vo/dto：存放视图对象、数据传输对象。禁止包名使用大写字母、特殊字符，禁止层级过深（建议不超过5层）。2.6其他命名接口命名：遵循类命名规范（PascalCase），以“Interface”结尾或直接使用业务名词（推荐后者），如：UserService（接口）、OrderDao（接口）。参数命名：遵循驼峰命名法，与变量命名一致，清晰反映参数含义，如：voidaddUser(StringuserName,Integerage)。常量接口：若使用常量接口，接口名以“Constants”结尾，如：UserConstants、SystemConstants，接口内仅定义常量，不包含方法。3.代码格式规范3.1缩进与换行缩进：采用4个空格缩进（禁止使用Tab键，避免不同编辑器显示不一致），每级缩进统一为4个空格。换行：每个独立的语句、表达式单独占一行，禁止多个语句写在同一行，如：代码块（if、for、while、try等）：左大括号“{”紧跟语句末尾，不单独换行；右大括号“}”单独占一行，与对应的语句对齐，如：方法体、类体的缩进：类内的成员变量、方法，统一缩进4个空格；方法内的代码块，再缩进4个空格，依次类推。空行：不同逻辑块、不同方法之间，用1个空行分隔；类的成员变量与方法之间，用1个空行分隔；方法内的不同逻辑段（如参数校验、业务处理、返回结果），用1个空行分隔，避免代码拥挤。3.2空格使用运算符两侧：双目运算符（+、-、*、/、==、!=、>、<、&&、||等）两侧各加1个空格，如：intsum=a+b;if(a==b){...}。单目运算符：单目运算符（++、--、!、~等）与操作数之间无空格，如：i++、!isExist、~num。括号两侧：括号内侧无空格，外侧有空格（特殊场景除外），如：if(a>0){...}、List<User>userList=newArrayList<>();。逗号、分号：逗号后加1个空格，分号后加1个空格（若分号在一行末尾，可省略空格），如：List<String>list=Arrays.asList("a","b","c");、for(inti=0;i<10;i++){...}。方法参数：参数之间的逗号后加1个空格，如：voidaddUser(StringuserName,Integerage,Stringphone)。注解：注解与类、方法、变量之间无空格，注解内的参数，逗号后加1个空格，如：@RequestMapping("/user")、@Param("userId")IntegeruserId。3.3代码长度限制单行代码长度：建议不超过120个字符，若超过，需换行拆分，拆分原则：在运算符、逗号后换行，换行后缩进4个空格，与上一行的运算符对齐，如：方法长度：单个方法的代码行数建议不超过80行（特殊复杂逻辑可适当放宽，但不超过100行），超过则需拆分方法，提取重复逻辑为子方法。类长度：单个类的代码行数建议不超过500行，超过则需拆分类，按功能拆分多个类（如拆分工具类、拆分实体类）。3.4导入包规范导入包需按需导入，禁止导入无用的包（IDE可自动删除无用导入）。导入包的顺序：先导入Java核心包（java.*），再导入第三方包（如org.*、com.*），最后导入项目自身包，不同类型的包之间用1个空行分隔，如：禁止使用通配符“*”导入包（除非导入的包数量超过10个，且属于同一包下的类，如：importjava.util.*;，但不推荐）。若导入的类名相同，需指定完整包名，避免歧义，如：ject.entity.Useruser=newject.entity.User();。4.注释规范4.1注释原则注释需准确、简洁，与代码逻辑一致，禁止注释与代码矛盾，禁止无用注释（如//这里是循环、//定义变量a）。注释需突出重点，复杂逻辑、关键算法、异常处理、特殊场景必须添加注释，简单逻辑（如inta=1;）可省略注释。注释语言：统一使用中文，禁止使用英文、拼音或混合语言（特殊术语可保留英文，如“DTO”“DAO”，需搭配中文说明）。注释格式：遵循JavaDoc规范，便于IDE生成文档，同时保持格式统一。4.2类注释每个类（包括接口、枚举、工具类）必须添加类注释，位于类定义上方，使用/**...*/格式，包含以下内容（根据类的类型调整）：类的用途、功能描述。作者（@author）：格式为“姓名/昵称<邮箱>”。创建日期（@date）：格式为“yyyy-MM-dd”。版本（@version）：可选，格式为“版本号，如1.0.0”。备注（@note）：可选，特殊说明（如类的设计思路、依赖关系等）。示例：java

/**

*用户控制器

*处理用户相关的请求（查询、新增、修改、删除），作为请求入口，调用服务层方法处理业务逻辑

*@author张三<zhangsan@>

*@date2026-03-25

*@version1.0.0

*@note依赖UserService接口，接收前端参数需进行校验

*/

@RestController

@RequestMapping("/user")

publicclassUserController{

//类内容

}4.3方法注释每个公共方法（public）必须添加方法注释，位于方法定义上方，使用/**...*/格式；私有方法（private）若逻辑复杂，也需添加注释。方法注释需包含以下内容：方法功能描述：清晰说明方法的作用、实现逻辑。参数说明（@param）：每个参数需标注参数名、参数含义，格式为“@param参数名参数含义”，多个参数按参数顺序排列。返回值说明（@return）：标注返回值的类型、含义，若返回值为void，可省略@return。异常说明（@throws）：标注方法可能抛出的异常类型、异常原因，多个异常按异常类型顺序排列。备注（@note）：可选，特殊说明（如方法的注意事项、调用限制等）。示例：java

/**

*根据用户ID查询用户信息

*调用UserDao的selectById方法，查询用户的基本信息（姓名、年龄、状态等）

*@paramuserId用户ID，非空，长度不超过32位

*@returnUser用户实体对象，若未查询到，返回null

*@throwsBusinessException当userId为空或格式错误时抛出

*@note该方法需先校验userId的合法性，再执行查询

*/

publicUsergetUserById(StringuserId)throwsBusinessException{

if(StringUtils.isEmpty(userId)||userId.length()>32){

thrownewBusinessException("用户ID不合法");

}

returnuserDao.selectById(userId);

}4.4变量与常量注释成员变量（尤其是静态变量、常量）必须添加注释，说明变量的含义、用途、取值范围（可选）。局部变量：若逻辑简单、含义清晰，可省略注释；若变量含义模糊、用途特殊，需添加注释。示例：4.5代码块注释复杂代码块（如多分支判断、循环逻辑、算法实现），需在代码块上方添加注释，说明代码块的功能、逻辑思路。临时注释（如调试代码、未完成代码），需标注“TODO”“FIXME”，并说明原因，且上线前必须删除或完善，如：禁止使用//注释掉代码（调试时除外），无用代码需直接删除，避免代码冗余。5.代码编写规范5.1变量与常量变量初始化：变量声明时必须初始化（局部变量可在使用前初始化，但需确保使用前已赋值，避免空指针），如：StringuserName="";List<User>userList=newArrayList<>();。常量定义：常量必须使用final修饰，静态常量需添加staticfinal，常量值不可修改；禁止在方法内定义常量，常量需定义在类的顶部，按功能分类排列。变量作用域：尽量缩小变量的作用域，避免使用全局变量（成员变量），优先使用局部变量，减少变量的副作用。避免重复定义：禁止在同一作用域内重复定义同名变量，如：在同一个方法内，不能同时定义两个inta;。包装类与基本类型：优先使用基本类型（int、long、double、boolean等），除非需要null值（如数据库字段允许null），再使用包装类（Integer、Long、Double等）；避免自动装箱、拆箱频繁出现，影响性能。5.2方法编写方法职责：单个方法只负责一个功能，遵循“单一职责原则”，避免一个方法处理多个逻辑（如既处理参数校验，又处理业务逻辑，还处理返回结果封装）。参数数量：方法的参数数量建议不超过5个，若超过，可封装为DTO/VO对象，如：voidaddUser(UserDTOuserDTO)，而非voidaddUser(StringuserName,Integerage,Stringphone,Stringaddress,DatecreateTime)。参数校验：方法入口必须进行参数校验（尤其是公共方法），校验参数的非空、格式、取值范围等，避免非法参数导致的异常，如：返回值：方法返回值需清晰，避免返回null（除非明确说明），若返回集合，建议返回空集合（而非null），如：returnnewArrayList<>();，避免调用方处理null异常。避免重复代码：多个方法中出现的重复逻辑，需提取为公共方法（工具类方法或私有子方法），提高代码复用性。禁止递归：除非特殊场景（如树形结构遍历），否则禁止使用递归，递归易导致栈溢出，且可读性差，可替换为循环实现。5.3条件与循环if-else语句：条件表达式需清晰，避免复杂的嵌套（建议嵌套不超过3层），超过则需拆分方法或使用switch、策略模式。if语句后若只有一条语句，也需添加大括号“{}”，避免代码歧义，如：elseif的顺序：按条件的优先级排列，常用条件、简单条件放在前面，减少判断次数。禁止使用if(flag==true)、if(flag==false)，直接使用if(flag)、if(!flag)。switch语句：switch表达式的类型：优先使用int、enum类型，避免使用String类型（JDK7及以上支持，但性能略差）。每个case后必须添加break;（除非需要穿透，需添加注释说明），避免case穿透导致逻辑错误。switch语句必须添加default;，处理默认场景，避免未覆盖的情况，如：循环语句：for循环：用于固定次数的循环，循环变量的初始化、条件、递增/递减需清晰，避免死循环（如i++写成i--）。foreach循环：用于遍历集合、数组，简洁高效，优先使用，如：for(Useruser:userList){...}。while/do-while循环：用于不确定次数的循环，do-while循环需确保循环体至少执行一次，避免逻辑错误。循环优化：避免在循环内创建对象、执行耗时操作（如数据库查询、IO操作），尽量将耗时操作移到循环外；遍历集合时，若需频繁获取集合大小，可将大小赋值给局部变量，如：5.4异常处理异常捕获：使用try-catch-finally语句捕获异常，避免直接抛出Exception（需捕获具体异常类型），如：异常处理原则：捕获异常后，需进行有效处理（如日志记录、异常提示、回滚操作），禁止捕获异常后不做任何处理（空catch块）。禁止使用e.printStackTrace();（仅调试时使用），需使用日志框架（如Logback、Log4j）记录异常信息，便于问题排查。抛出异常时，需添加具体的异常信息，说明异常原因，如：thrownewBusinessException("用户ID不能为空")，而非thrownewBusinessException();。自定义异常：业务异常需自定义异常类，继承Exception或RuntimeException，区分系统异常与业务异常，便于统一处理。资源释放：使用try-with-resources语句（JDK7及以上）自动释放资源（如文件流、数据库连接），简化代码，如：5.5集合使用集合初始化：初始化集合时，尽量指定集合大小（尤其是已知集合元素数量时），减少集合扩容带来的性能损耗，如：List<User>userList=newArrayList<>(10);。集合选择：根据业务场景选择合适的集合，如：需要有序、可重复：ArrayList（查询快、增删慢）。需要增删快、查询慢：LinkedList。需要去重、无序：HashSet。需要去重、有序：TreeSet、LinkedHashSet。键值对存储：HashMap（无序）、TreeMap（有序）、LinkedHashMap（插入有序）。集合遍历：优先使用foreach循环，避免使用Iterator遍历（除非需要删除元素）；遍历HashMap时，若需同时获取键和值，使用entrySet()，避免使用keySet()遍历后再get(key)（性能差），如：java

//正确

for(Map.Entry<String,User>entry:userMap.entrySet()){

Stringkey=entry.getKey();

Useruser=entry.getValue();

//操作

}

//错误

for(Stringkey:userMap.keySet()){

Useruser=userMap.get(key);

//操作

}集合判空：使用CollectionUtils.isEmpty()（ApacheCommonsCollections）或Objects.nonNull()（JDK8及以上）判空，避免空指针，如：java

if(CollectionUtils.isEmpty(userList)){

return;

}禁止使用Vector、Hashtable等过时集合，优先使用ArrayList、HashMap等线程不安全集合（多线程场景需使用ConcurrentHashMap、CopyOnWriteArrayList等线程安全集合）。5.6其他规范避免使用魔法值：代码中禁止出现无意义的数字、字符串（魔法值），需将其定义为常量，如：字符串操作：字符串拼接：少量拼接使用“+”，大量拼接（如循环内）使用StringBuilder（非线程安全）或StringBuffer（线程安全），避免频繁创建String对象。字符串判空：使用StringUtils.isEmpty()或StringUtils.isBlank()（区分空字符串和空格），避免使用==、!=判断字符串是否相等（需使用equals()方法）。字符串常量：优先使用字符串常量池，如：Stringstr="abc";，避免使用newString("abc");（创建新对象，浪费内存）。日期时间操作：禁止使用Date、Calendar等过时类，优先使用JDK8及以上的java.time包下的类（LocalDateTime、LocalDate、LocalTime等）。日期格式化：使用DateTimeFormatter，避免SimpleDateFormat（线程不安全），如：封装性：类的成员变量需使用private修饰，提供getter/setter方法（必要时），禁止直接暴露成员变量；getter/setter方法需遵循标准命名，如：getUserName()、setUserName(StringuserName)。继承与实现：继承遵循“里氏替换原则”，子类可替换父类，且不改变原有逻辑。接口实现：实现类需实现接口的所有抽象方法，若无需实现，需将实现类定义为抽象类。禁止多重继承（Java不支持），可通过接口实现多继承的效果。6.安全规范输入校验：所有前端传入的参数、外部接口传入的参数，必须进