Java程序编码规范

Java程序编码规范前言Java作为企业级后端开发的主流语言，其编码规范是提升代码质量、降低维护成本、保障团队高效协作的核心准则。本规范以Oracle官方编码规范为基础，结合阿里巴巴《Java开发手册》最新黄山版v1.7.1的核心要求，涵盖编码格式、命名规范、注释规范、语法规范、异常处理、资源管理等全维度内容，适用于各类Java项目开发，旨在统一编码风格、杜绝常见隐患、打造高可读性、高健壮性、可扩展性的工业级代码，同时减少技术债务，适配业务长期迭代需求。一、通用基础规范1.1编码格式统一采用UTF-8编码格式，严禁使用GBK等其他编码，避免出现中文乱码问题；所有Java源文件必须以.java为后缀，且文件名需与公共类名完全一致（大小写敏感），否则会导致编译错误。1.2缩进与空格缩进统一使用4个空格，绝对禁止使用Tab键，建议在IDE（优先IDEA）中开启“将Tab替换为空格”配置，防止不同编辑器Tab显示宽度不一致导致排版错乱；空格使用遵循“松紧适度、清晰分隔”原则，具体要求如下：二元运算符（+、-、*、/、==、!=、>、<、&&、||等）左右必须各加1个空格，例如inttotal=count*price+discount;，严禁写成inttotal=count*price+discount;。一元运算符（++、--、!、~等）紧贴变量，不加空格，例如index++、!isValid。方法参数列表、for循环、while循环内部的逗号分隔符后，必须加1个空格；括号与内部内容之间不加空格，例如if(userExist)，而非if(userExist)。数组定义时，中括号紧贴数据类型，而非变量名，规范写法为String[]userArray，禁止写法StringuserArray[]。1.3换行与空行单行代码长度严格控制在120字符以内，超长代码需按逻辑拆分换行，换行后缩进4个空格，保持对齐，避免横向滚动查看。所有流程控制语句（if、for、while、do-while、switch、try-catch），无论内部代码行数多少，必须添加大括号，杜绝单行语句省略大括号的写法，避免后续新增代码时出现逻辑嵌套错误。大括号遵循“左大括号不换行，右大括号单独成行”的标准，else、catch、finally紧跟右大括号时可不单独换行，例如if(flag){...}else{...}。方法、内部类、独立代码块之间必须空1行；逻辑紧密的连续代码不随意空行，禁止连续出现2行及以上空行；文件末尾必须保留1个空行，避免代码合并或编译异常。import语句分组排序，静态导入与普通导入分开，中间空1行；删除所有未使用的导入包，严禁使用通配符导入（如importjava.util.*），避免类冲突。1.4IDE配置要求团队需统一IDE格式化配置，IDEA用户推荐导入阿里编码规约格式化模板，开启“保存时自动格式化”“自动优化导入包”功能，从工具层面杜绝格式不规范问题；所有开发者提交代码前，必须执行格式化操作，确保代码格式统一。二、命名规范命名核心原则：望文知义、简洁准确、长度适中，使用标准英文单词或行业通用缩写（如URL、HTML），严禁使用拼音、拼音首字母、无意义字母（a、b、tmp等）、含糊泛称；命名只能由字母、数字、下划线、$符号组成，不能以数字开头，不能使用Java关键字。2.1包命名全部使用小写字母，多层包用点分隔，采用“域名倒置+业务模块”的规范，确保全局唯一性，包名统一使用单数形式，例如ject.user、ject.order；避免使用下划线或驼峰命名，禁止出现ject.user_service这类写法。2.2类、接口、枚举命名统一采用大驼峰命名法（UpperCamelCase），首字母大写，后续每个单词首字母大写，使用名词或名词短语，精准体现职责与定位：普通类：体现业务领域与功能，杜绝泛称，例如UserLoginService、OrderPayHandler，禁止UserService、MyUtil。抽象类：以Abstract或Base开头，例如AbstractUserService、BaseController。异常类：以Exception结尾，例如UserNotFoundException、OrderOperateException。工具类：以Util结尾，例如RedisConfigUtil、DateUtil，工具类需设计为单例或全静态方法。测试类：以被测试类名开头、Test结尾，例如UserServiceTest、OrderMapperTest。接口：命名与类一致，无需添加I前缀，实现类以Impl结尾，例如接口UserService，实现类UserServiceImpl。枚举类：以Enum结尾，例如ErrorCodeEnum、OrderStatusEnum。领域模型：数据对象（DO）以DO结尾（对应数据表名），数据传输对象（DTO）以DTO结尾，展示对象（VO）以VO结尾，例如UserDO、OrderDTO、UserVO；POJO是DO/DTO/VO的统称，禁止命名为xxxPOJO。2.3方法命名采用小驼峰命名法（lowerCamelCase），首字母小写，后续每个单词首字母大写，使用动词或动词短语，体现行为逻辑，遵循行业通用惯例：查询方法：以get、list、query开头，例如getUserById、listOrderByCondition、queryUserCount。新增方法：以add、save开头，例如addUser、saveOrder（推荐save）。更新方法：以update开头，例如updateUserInfo、updateOrderStatus。删除方法：以delete、remove开头，例如deleteUser、removeOrder（推荐remove）。判断方法：以is、has开头，返回值为boolean，例如isUserExist、hasPermission。2.4变量与参数命名成员变量、局部变量、方法参数：采用小驼峰命名法，使用名词，表达存储内容，禁止含糊命名，例如userName、mobilePhone，禁止tmp、a、param1。临时变量：循环变量可使用i、j、k、m、n（整数），c、d、e（字符），例如for(inti=0;i<list.size();i++)。布尔类型变量：不要加is前缀，否则部分框架解析会引起序列化错误，例如booleanenable，禁止booleanisEnable。集合、数组命名：体现数据类型与数量，使用复数形式或业务后缀，例如userList、orderMap、ipAddressArray。2.5常量命名全部使用大写字母，单词之间用下划线分隔，必须添加staticfinal修饰，清晰体现用途与取值范围，避免缩写（除非通用缩写），例如publicstaticfinalintMAX_THREAD_SIZE=10;、publicstaticfinalStringSUCCESS_CODE="0000";；严禁使用魔法值（未定义的常量直接出现在代码中），例如禁止if(code.equals("0000"))，需替换为常量引用。2.6泛型参数命名使用单个大写字母，遵循行业惯例：T（Type，类型）、E（Element，元素）、K（Key，键）、V（Value，值），例如List<T>、Map<K,V>。三、注释规范注释核心原则：简洁、准确、有用，用于补充代码中不易直观理解的信息，避免冗余注释；注释应包含与代码相关的关键信息，不包含包构建方式、文件路径等无关内容；当觉得需要添加注释时，优先考虑重构代码使其更清晰，而非依赖注释。3.1注释类型Java支持两种注释：实现注释（//、/*...*/）和文档注释（/**...*/），其中文档注释是Java特有，可通过javadoc工具提取为HTML文档，供开发者快速查阅接口、类的用途。3.2文档注释（/**...*/）用于类、接口、方法、常量的说明，必须包含核心信息，格式统一，使用@标签补充细节，具体要求如下：类/接口注释：位于类/接口定义上方，说明类/接口的用途、职责、设计思路，可包含@author（作者）、@version（版本）、@since（引入版本）等标签，例如：

/**

*用户服务接口，负责用户注册、登录、信息管理等核心业务逻辑

*@author开发者姓名

*@version1.0

*@since2026-03-01

*/

publicinterfaceUserService{}方法注释：位于方法定义上方，说明方法的功能、参数含义、返回值、异常信息，可包含@param（参数）、@return（返回值）、@throws（异常）等标签，例如：

/**

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

*@paramuserId用户ID，非空且长度为10位字符串

*@returnUserVO用户信息封装对象，查询不到时返回null

*@throwsUserNotFoundException当用户ID不存在时抛出

*/

publicUserVOgetUserById(StringuserId)throwsUserNotFoundException{}常量注释：位于常量定义上方，说明常量的含义、取值范围，例如：

/**

*成功状态码，标识接口请求成功

*/

publicstaticfinalStringSUCCESS_CODE="0000";3.3实现注释（//、/*...*/）用于注释代码逻辑、临时注释、调试说明，分为单行注释、块注释、尾随注释，具体要求如下：单行注释（//）：用于注释单行代码或简短说明，位于代码上方或右侧，上方注释需空1行，例如：

//计算订单总金额（不含折扣）

inttotalAmount=count*price;

intfinalAmount=totalAmount-discount;//扣除折扣后的最终金额块注释（/*...*/）：用于注释代码块、复杂逻辑说明，可用于文件开头、方法内部，块注释前需空1行，缩进与对应代码一致，禁止用星号等字符绘制边框，例如：

/*

*批量处理订单状态更新

*1.筛选出待更新的订单列表

*2.循环更新每个订单的状态

*3.记录更新日志，便于后续排查

*/

List<OrderDO>orderList=getPendingOrderList();

for(OrderDOorder:orderList){

updateOrderStatus(order);

("订单{}状态更新为{}",order.getOrderId(),order.getStatus());

}尾随注释：仅用于简单说明，避免过长，例如intindex=0;//循环起始索引。3.4注释禁忌禁止注释冗余信息：避免注释与代码完全重复，例如inta=1;//给a赋值为1。禁止注释过时代码：删除无用的注释代码，避免误导开发者；临时注释需标注日期，后续及时清理。禁止使用特殊字符：注释中不得包含换页符、退格符等特殊字符。禁止注释无关内容：不包含代码之外的无关信息，如个人备注、开发日志等。四、语法与编程规范4.1变量与常量变量声明：变量必须先声明后使用，严禁未声明直接赋值；局部变量必须初始化，避免空指针异常；成员变量若未初始化，需明确其默认值含义。常量定义：常量应放在类的顶部，集中管理，便于维护；避免在方法内部定义常量（应使用局部变量替代）。变量作用域：最小化变量作用域，避免定义全局变量（除非必要）；局部变量仅在当前代码块中使用，用完及时释放。4.2方法设计单一职责：一个方法只做一件事，方法长度控制在80行以内，避免过长方法（超过80行需拆分），提升可读性和可维护性。参数数量：方法参数个数控制在5个以内，超过5个时，建议封装为DTO对象，例如createOrder(OrderDTOorderDTO)，禁止createOrder(StringorderId,StringuserId,BigDecimalamount,DatecreateTime,Stringstatus)。返回值：返回值需明确，避免返回null（可返回空集合、Optional对象替代）；返回值类型需与方法功能匹配，不返回无关数据。方法访问修饰符：严格控制访问权限，优先使用private，其次protected，最后public；无需对外暴露的方法，一律使用private。4.3流程控制if-else：避免多层嵌套（建议不超过3层），多层嵌套可拆分为方法或使用switch、策略模式优化；if-elseif-else顺序合理，高频条件放前面。switch：case语句必须添加break（除非有意穿透），default语句必须存在（处理异常情况）；switch表达式优先使用枚举或常量，禁止使用魔法值。循环：for循环避免死循环，明确循环终止条件；foreach循环适用于遍历集合，避免在循环中修改集合（易引发ConcurrentModificationException）；循环体内避免执行耗时操作（如数据库查询、网络请求）。4.4数组与集合数组：避免使用空数组（可使用空集合替代）；数组初始化时，指定初始容量（已知容量时），提升性能。集合：优先使用接口声明集合，具体实现类在初始化时指定，例如List<User>userList=newArrayList<>();，禁止ArrayList<User>userList=newArrayList<>();。集合操作：遍历集合时，避免使用for循环（通过索引访问），优先使用foreach或迭代器；集合判空使用CollectionUtils.isEmpty()（ApacheCommons工具类），禁止list==null||list.size()==0。不可变集合：无需修改的集合，使用不可变集合，例如Collections.unmodifiableList(list)，避免误修改。4.5字符串操作字符串拼接：少量拼接使用+，大量拼接（如循环中）使用StringBuilder（非线程安全）或StringBuffer（线程安全），避免产生大量字符串常量，浪费内存。字符串判空：使用StringUtils.isEmpty()或StringUtils.isBlank()（ApacheCommons工具类），区分“空字符串”和“空白字符串”；禁止str==null||str.equals("")。常量字符串：优先使用字符串常量池，避免频繁创建相同字符串对象，例如Stringstr="hello";，禁止Stringstr=newString("hello");。五、异常处理规范异常处理核心原则：精准捕获、合理处理、详细记录，避免吞掉异常、滥用try-catch，确保异常可排查、不影响系统稳定性。5.1异常捕获精准捕获：捕获具体异常（如NullPointerException），禁止捕获笼统的Exception（除非有特殊需求），避免掩盖真正的异常。try-catch范围：最小化try-catch范围，仅包裹可能抛出异常的代码，避免将无关代码放入try块。多异常捕获：多个异常可合并捕获（使用|分隔），例如catch(NullPointerException|IllegalArgumentExceptione)，避免重复处理逻辑。5.2异常处理禁止吞掉异常：catch块中严禁空处理（catch(Exceptione){}），至少记录异常日志，便于排查。异常日志：记录异常时，需包含异常信息、异常堆栈、业务上下文（如参数信息），使用log.error("业务描述，参数：{}",param,e)，禁止log.error("异常信息："+e.getMessage())（丢失堆栈信息）。异常抛出：自定义异常需继承Exception或RuntimeException，根据业务场景选择；抛出异常时，需添加详细描述，例如thrownewUserNotFoundException("用户ID："+userId+"不存在")。try-catch-finally：finally块用于释放资源（如流、数据库连接），确保资源无论是否异常都会被释放；避免在finally块中修改返回值（会覆盖try/catch中的返回值）。5.3异常禁忌禁止滥用异常：不使用异常控制流程（如用异常替代if判断），异常仅用于处理异常情况。禁止抛出未声明的异常：非运行时异常（checkedexception）必须在方法上声明throws，或在方法内捕获处理。禁止重复抛出异常：避免catch(Exceptione){throwe;}，可直接抛出原异常，或包装为自定义异常后抛出（需保留原异常堆栈）。六、资源管理规范资源管理核心原则：及时释放资源，避免资源泄漏，尤其是文件流、数据库连接、网络连接等稀缺资源。6.1流资源使用try-with-resources语法（Java7及以上）自动关闭流资源，无需手动调用close()方法，例如：java

try(FileInputStreamfis=newFileInputStream("file.txt");

FileOutputStreamfos=newFileOutputStream("output.txt")){

//流操作逻辑

}catch(IOExceptione){

log.error("文件流操作异常",e);

}若使用Java7以下版本，需在finally块中手动关闭流，关闭时需判断资源是否为null，避免空指针异常。6.2数据库资源数据库连接：使用连接池管理连接（如Druid、HikariCP），禁止手动创建连接（DriverManager.getConnection()），避免连接泄漏。Statement/PreparedStatement：使用PreparedStatement替代Statement，防止SQL注入；使用后及时关闭，可通过try-with-resources自动关闭。事务管理：明确事务边界，避免事务过大（包含非数据库操作）；事务异常时，需及时回滚，避免数据不一致。6.3其他资源线程资源：使用线程池管理线程，禁止频繁创建和销毁线程；线程执行完毕后，确保资源释放，避免线程泄漏。缓存资源：缓存数据需设置过期时间，避免缓存膨胀；缓存更新时，确保缓存与数据库数据一致，避免数据脏读。七、并发编程规范线程安全：共享变量需保证线程安全，使用synchronized、volatile、Lock等机制；避免使用线程不安全的集合（如ArrayList、HashMap），多线程环境下优先使用ConcurrentHashMap、CopyOnWriteArrayList等线程安全集合。volatile关键字：仅用于保证变量可见性，不能保证原子性，避免滥用volatile替代synchronized。synchronized：锁定粒度最小化，优先锁定代码块，而非整个方法；避免锁定全局对象（如this、Class对象），防止死锁。线程池：统一配置线程池参数（核心线程数、最大线程数、队列容量、拒绝策略），避免使用Executors默认创建线程池（易引发OOM）。死锁避免：避免多个线程持有不同锁的情况下，相互等待对方释放锁；尽量按顺序获取锁，减少死锁概率。八、安全规范SQL注入防护：使用PreparedStatement、参数绑定，禁止字符串拼接SQL；输入参数严格校验，过滤特殊字符。XSS攻击防护：对用户输入的字符串进行转义处理，避免恶意脚本注入；使用安全框架（如SpringSecurity）辅助防护。敏感信息保护：密码、密钥等敏感信息，需加密存储（如MD5、SHA256加密），禁止明文存储；传输过程中使用HTTPS加密。权限控制：接口访问需进行权限校验，禁止未授权访问；根据用户角色分配最小权限，避免越权操作。九、工程结构规范遵循分层架构（Controller、Service、Dao/Repository），结构清晰，职责明确，便于维护和扩展，标准工程结构如下：java

ject

├──common//公共模块（工具类、常量、异常、通用DTO）

├──config//配置类（数据库、缓存、线程池等配置）

├──controller//控制层（接收请求、返回响应，不处理业务逻辑）

├──service//