JAVA|后端编码规范

零、引言

一、基础

二、集合

三、并发

四、日志

五、安全

零、引言

规范等级：

【强制】：强制遵守，来源于线上历史故障，将通过工具进行检查。
【推荐】：推荐遵守，来源于日常代码审查、开发人员反馈和行业经验。

一、基础

序号

等级

规范

示例

说明

强制

在POJO类中定义布尔类型成员变量时，禁止用is作变量名前缀。

反例：

private boolean isDeleted;

// Getter方法：IDEA生成，与变量同名。

public boolean isDeleted() {

return isDeleted;

}

// Setter方法：IDEA生成

public void setDeleted(boolean deleted) {

isDeleted = deleted;

}

is作变量名前缀的布尔型成员变量，在一些IDE（如：IDEA）中，默认生成的getter方法与变量名相同，导致部分框架（如：Jackson、Fastjson）在反向解析时会引发“找不到指定成员变量名”的错误。

强制

在对象之间做相等比较时，应当使用Objects工具类（java.util.Objects）的equals方法。

正例：

String versionNo = "6.6.1";

// 如param为null，不会出现异常。

Objects.equals(param, versionNo);

反例：

String versionNo = "6.6.1";

// 如param为null，会出现异常。

param.equals(versionNo);

当对象为null时，直接调用equals会出现空指针异常。

注意：Objects的equals方法内部会利用参数对象的equals方法进行比较，对数组、集合之类的对象并不会做内部元素的一一比较。

强制

在BigDecimal之间做等值比较时，禁止使用equals方法。

正例：

// 商品原价格

BigDecimal skuPrice = new BigDecimal("120.00");

// 商品优惠后价格

BigDecimal skuPromoPrice = new BigDecimal("120.0");

// 使用compareTo做比较，不会比较精度。

if (skuPrice.compareTo(skuPromoPrice) == 0) { // true

// ...

}

反例：

// 商品原价格

BigDecimal skuPrice = new BigDecimal("120.00");

// 商品优惠后价格

BigDecimal skuPromoPrice = new BigDecimal("120.0");

// 使用equals做比较，会比较精度。

if (skuPrice.equals(skuPromoPrice)) { // false

// ...

}

BigDecimal的equals方法会比较精度，如1.0与1.00比较的结果为false，推荐使用其

compareTo方法做比较。

强制

在浮点数之间做等值比较时，基本类型禁止使用==，包装类型禁止使用equals。

正例：

// 下方减法运算是为了故意引起浮点误差

// 时段一的单价：充电站单价 - 优惠价

float timePrice1 = 1.0F - 0.9F;

// 时段二的单价：充电站单价 - 优惠价

float timePrice2 = 0.9F - 0.8F;

// 工具类推荐：org.apache.commons.lang3.math.NumberUtils

// 将浮点数转为BigDecimal并指定保留位数和取舍方式

BigDecimal decimalTimePrice1 = NumberUtils.toScaledBigDecimal(timePrice1, 2, RoundingMode.HALF_UP);

BigDecimal decimalTimePrice2 = NumberUtils.toScaledBigDecimal(timePrice2, 2, RoundingMode.HALF_UP);

if (decimalTimePrice1.compareTo(decimalTimePrice2) == 0) { // true

// ...

}

反例：

// 下方减法运算是为了故意引起浮点误差

// 时段一的单价：充电站单价 - 优惠价

float timePrice1 = 1.0F - 0.9F;

// 时段二的单价：充电站单价 - 优惠价

float timePrice2 = 0.9F - 0.8F;

// 可能存在浮点误差，等式不成立。

if (timePrice1 == timePrice2) { // false

// ...

}

反例：

// 下方减法运算是为了故意引起浮点误差

// 时段一的单价：充电站单价 - 优惠价

Float timePrice1 = 1.0F - 0.9F;

// 时段二的单价：充电站单价 - 优惠价

Float timePrice2 = 0.9F - 0.8F;

// 可能存在浮点误差，等式不成立。

if (timePrice1.equals(timePrice2)) { // false

// ...

}

浮点数先转成BigDecimal，再用compareTo方法做比较，以避免精度问题影响结果。

浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分的十进制小数。

强制

将浮点数转换为BigDecimal 时，禁止直接使用构造方法。

正例：

// 商品SKU单价

double skuPrice = 0.1D;

// 工具类推荐：org.apache.commons.lang3.math.NumberUtils

// 精度不影响，仍然是0.1。

BigDecimal decimalSkuPrice = NumberUtils.createBigDecimal(Double.toString(skuPrice));

反例：

// 商品SKU单价

double skuPrice = 0.1D;

// 精度受影响，可能是0.1000000000000000055511151231257827021181583404541015625。

BigDecimal decimalSkuPrice = new BigDecimal(skuPrice);

BigDecimal的浮点数构造方法存在精度损失风险，在精确计算或值比较的场景中会导致业务逻辑异常。

注意：和上一条的正例不同的是，前者在经过浮点计算后已经形成了误差，在转换时用toScaledBigDecimal方法限定了精度。在此处，是为了避免因直接利用浮点数构造而导致的误差。

强制

在空指针异常易发的场景中，应当对对象做null判断。

正例：

@Resource

private UserService userService;

public String queryCityName(String userId) {

User userObj = userService.queryUserInfo(userId);

Optional<User> userData = Optional.ofNullable(userObj);

Optional<UserAddress> userAddress = userData.map(User::getUserAddress);

// 如用户地址为null，不会空指针异常。

Optional<String> optionalCityName = userAddress.map(UserAddress::getCiyName);

// null时返回默认值

String cityName = optionalCityName.orElse(DEFAULT_CITY);

return cityName;

}

反例：

@Resource

private UserService userService;

public String queryCityName(String userId) {

User userObj = userService.queryUserInfo(userId);

// 如用户地址为null，会空指针异常。

String cityName = userObj.getUserAddress().getCiyName();

return cityName;

}

在对象未判断null的情况下直接引用，容易发生空指针异常，推荐用Optional类更优雅的处理null对象。

一些空指针异常（NPE）易发的场景：

返回类型为基本数据类型，return包装数据类型的对象时，自动拆箱有可能产生NPE。
数据库的查询结果可能为null
集合里的元素即使isNotEmpty，取出的数据元素也可能为null。
远程调用返回对象时，一律要求进行空指针判断，防止NPE。
对于Session中获取的数据，建议进行NPE检查，避免空指针。
级联调用obj.getA().getB().getC()，一连串调用，易产生NPE。

强制

在日期格式化时，应当使用DateUtils工具类

正例

Calendar calendar = Calendar.getInstance();

// 日期是2023-12-31

calendar.set(2023, 11, 31);

// strDateTime：2023-12-31

String strDateTime = DateUtils.datesToString(calendar.getTime());

反例

Calendar calendar = Calendar.getInstance();

// 日期是2023-12-31

calendar.set(2023, 11, 31);

// 误用了大写Y格式化年份

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("YYYY-MM-dd");

// strDateTime：2024-12-31

String strDateTime = simpleDateFormat.format(calendar.getTime());

DateUtils包装了常用的日期格式，避免了手动格式化时的误用风险，如：年份格式化误书写成YYYY，如本周存在跨年的情况，返回的就是下一年。

强制

POJO类属性，禁止使用基本数据类型。

正例

@Resource

private UserRepository userRepository;

public Integer queryUserId(String phone) {

// getUserIdByPhone返回的是Integer类型，当返回null时，不会出现空指针异常。

Integer userId = userRepository.getUserIdByPhone(phone);

// 可以做防御性校验，以避免直接空指针

if(userId != null){

// …

}

// …

}

反例：

@Resource

private UserRepository userRepository;

public int queryUserId(String phone) {

// getUserIdByPhone返回的是Integer类型，当返回null时，会出现空指针异常。

int userId = userRepository.getUserIdByPhone(phone);

// …

}

POJO类属性使用包装数据类型有如下优点：

若值为null时，能显式的提醒使用者做相应的处理，而不是使用基本数据类型的默认值。
避免对象之间的自动拆装箱时出现NPE。

二、集合

序号

等级

规范

示例

说明

强制

在需要对List的subList方法返回结果进行遍历、增加、删除元素时，禁止直接变更原List中的元素。

反例：

List<String> cityList = new ArrayList<>();

cityList.add("北京");

cityList.add("上海");

cityList.add("广州");

List<String> citySubList = cityList.subList(0, 1);

// subList之后变更原List

cityList.add("深圳");

// 出现ConcurrentModificationException异常

for (int i = 0; i < citySubList.size(); i++) {

// ...

}

List的subList方法返回的是一个List的内部类对象，它是List的一个视图，对原List所有的操作都会反映到这个对象上。

同时，对原List进行元素的增加或删除，会被计数（modCount，结构变更次数），此数值和原subList时记录的数值（expectedModCount）不一致，会引发ConcurrentModification

Exception异常。

强制

对集合进行for循环时，禁止在循环体内用remove/add方法。

正例：

List<String> cityList = new ArrayList<>();

cityList.add("北京");

cityList.add("上海");

cityList.add("广州");

Iterator<String> iterator = cityList.iterator();

while (iterator.hasNext()) {

String city = iterator.next();

// 工具类推荐：org.apache.commons.lang3.StringUtils

if (StringUtils.equals("广州", city)) {

iterator.remove();

}

反例：

List<String> cityList = new ArrayList<>();

cityList.add("北京");

cityList.add("上海");

cityList.add("广州");

// 出现ConcurrentModificationException异常

for (String city : cityList) {

// 工具类推荐：org.apache.commons.lang3.StringUtils

if (StringUtils.equals("广州", city)) {

cityList.remove(city);

}

若在for循环体内对集合元素进行remove/add操作，可能导致异常，建议使用iterator方式处理。

三、并发

序号

等级

规范

示例

说明

强制

动态线程池只允许使用通义管理平台定义的（比如Poseidon），禁止自行创建。

正例：

// poseidonThreadPool在Poseidon管理平台已创建

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

CompletableFuture.supplyAsync(() -> {

// ...

}, poseidonThreadPool);

反例：

// 自建线程池，未接入Poseidon。

ThreadPoolExecutor customThreadPool = new ThreadPoolExecutor(corePoolSize,

maximumPoolSize,

keepAliveTime,

unit,

workQueue,

new ThreadPoolExecutor.AbortPolicy());

CompletableFuture.supplyAsync(() -> {

// ...

}, customThreadPool);

通过Poseidon创建的线程池将能较好的进行管理和监控：

支持通过Poseidon动态修改线上线程池参数（线程数量、队列长度、拒绝策略），无需重启服务即可生效。
CAT平台能对线程池状态进行监控和告警。

强制

在使用线程池时，禁止将拒绝策略设置为DiscardPolicy。

反例：

// poseidonThreadPool在Poseidon管理平台已创建，且配置了DiscardPolicy拒绝策略。

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

public void process(){

// ...

// 队列满且已达到最大线程数后，任务会被自动抛弃。

Future<String> resultFuture = poseidonThreadPool.submit(task);

// ...

}

若配置了DiscardPolicy，当线程池队列排满且已达到了最大线程数后，新增任务会被直接丢弃，无任何提示，并且在结合future.get()运行时，存在阻塞的风险。

强制

父子任务禁止使用同一个线程池。

反例：

class OrderManager {

// Poseidon配置的线程池

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

@Autowired

private ProductManager productManager;

public List<Order> queryOrders() throws Exception {

// ...

// 如果子任务出现阻塞，父任务一直等待。

Future<Order> orderFuture = poseidonThreadPool.submit(() -> {

// ...

ProductInfo product = productManager.queryProducts(orderId);

// ...

});

orderFuture.get();

// ...

}

class ProductManager {

// Poseidon配置的线程池

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

public List<ProductInfo> queryProducts(String orderId) throws Exception {

// ...

// 子任务存在多线程处理，且使用了同一个线程池。

Future<ProductInfo> productFuture = poseidonThreadPool.submit(() -> {

// ...

});

productFuture.get();

// ...

}

父子任务使用同一个线程池容易相互影响，线程数达上限时，子任务等待线程资源，而同时，父任务因子任务未完成，其资源得不到释放，最终可能导致相互等待或死锁。

强制

在多线程环境下，禁止直接使用HashMap。

正例：

// poseidonThreadPool在Poseidon管理平台已创建

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

public void process() {

// ConcurrentHashMap是线程安全的

Map<String, String> map = new ConcurrentHashMap<>();

CompletableFuture.supplyAsync(() -> {

// ...

map.put("key1", "value1");

// ...

}, poseidonThreadPool);

CompletableFuture.supplyAsync(() -> {

// ...

map.put("key2", "value2");

// ...

}, poseidonThreadPool);

}

反例：

// poseidonThreadPool在Poseidon管理平台已创建

@Resource(name = "poseidonThreadPool")

private ThreadPoolExecutor poseidonThreadPool;

public void process() {

// HashMap是线程不安全的

Map<String, String> map = new HashMap<>();

CompletableFuture.supplyAsync(() -> {

// ...

map.put("key1", "value1");

// ...

}, poseidonThreadPool);

CompletableFuture.supplyAsync(() -> {

// ...

map.put("key2", "value2");

// ...

}, poseidonThreadPool);

}

HashMap是线程不安全的，在容量不够进行resize时，可能因并发出现死链，导致CPU飙升。

四、日志

序号

等级

规范

示例

说明

强制

日志级别只允许使用ERROR、WARN、INFO、DEBUG。

正例：

// ...

// info打印业务关键信息

log.info("操作人id：{}", operatorUserId);

// ...

List<UserData> userDataList = userListService.selectUsers();

// debug打印开发调试信息

log.debug("开始执行时间：{}", System.currentTimeMillis());

userDataList.stream().forEach(userData -> {

// ...

});

log.debug("结束执行时间：{}", System.currentTimeMillis());

ERROR：业务功能受损或无法完成预期操作，可能会造成线上故障需要预警并及时解决，否则该功能将无法正常运行。
WARN：异常符合预期的情况且业务不受损，不会出现线上故障，可根据实际情况选择性预警，解决时效要求不高，但需要关注。
INFO：用于记录系统运行过程或重要信息点，主要为故障定位、过程追溯、数据分析等提供辅助。
DEBUG：用于在测试或本地的非生产环境中使用，可以记录详细的信息，主要为了方便开发调试程序，在生产环境中禁止使用。

强制

业务受损或预期外的异常场景，应当打印ERROR日志。

正例：

try {

// ...

// 发送短信验证码

loginService.sendVerificationCode(cellphone);

// ...

} catch (Exception ex) {

// 预期外的系统错误，业务受损。

log.error("异常场景：{}, 异常数据：{}", "用户H5登录", userId, ex);

// 异常处理

}

反例：

try {

// ...

// 发送短信验证码

loginService.sendVerificationCode(cellphone);

// ...

} catch (Exception ex) {

log.info("异常场景：{}, 异常数据：{}", "用户H5登录", userId, ex);

// 异常处理

}

ERROR日志用于描述异常不可控的场景，当该类异常发生的时候会给业务和系统带来伤害，需要第一时间告警并介入排查修复。

强制

业务不受损且预期内的异常场景，应当打印WARN日志。

正例：

public List<User> selectUserByHeight(Integer height) {

// ...

// 该校验偶发于用户录入出错的情况下，需观测是否频繁以指导进一步处理。

// 如：可能上游系统BUG导致度量单位搞错

if (height > 270) {

log.warn("异常场景：{}，身高：{} 不能大于270cm", "用户H5注册", height);

// ...

}

// ...

}

WARN日志用于描述异常可控的场景，当该类异常发生的时候不会给业务和系统带来伤害，用于记录和观测，指导进一步处理。

五、安全

序号

等级

规范

示例

说明

强制

用户敏感数据禁止直接展示、禁止用Get方式提交。

反例：

@Resource

private UserService userService;

public BizResponse<List<UserDTO>> getAllUsers() {

List<User> users = userService.selectAllUsers();

List<UserDTO> userDTOs = new ArrayList<>();

users.forEach(user -> {

UserDTO userDTO = new UserDTO();

// 手机号码此处没有脱敏，直接返回到前端。

userDTO.setPhone(user.getPhone());

// ...

userDTOs.add(userDTO);

});

return BizResponse.success(userDTOs);

}

手机号、银行卡卡号、身份证、车牌、车架号等都属于用户敏感信息，不能直接展示。

脱敏方式：

手机号保留前3位和后4位；
身份证号保留前6位和后3位；
银行卡前6位和后4位；
车牌将视情况按照保留地区和流水号后2位；
车架号将视情况按照保留后6位；

禁止用Get方式提交，这种方式在URL上带有敏感数据，将会在wan/lan日志中出现这些元数据。

强制

用户输入的参数，禁止直接拼接到SQL访问数据库。

反例：

<select id="findUser" resultType="com.tuhu.mysql.User">

select * from userInfo where username = ${userName}

</select>

// Mapper接口

public UserInfo findUser(String userName)

用户输入的参数可能带有SQL片段，存在SQL注入的风险，需要使用参数绑定的技术来防范。

强制

未经许可，禁止外发公司任何程序代码。

反例：

为了交流学习，将公司代码上传至GitHub，以方便各方来阅读和讨论，导致APPID、API等信息泄漏。

程序代码属于公司资产，在未经许可的情况下不得以任何方式（邮件、IM软件、纸质打印等）向外传输或公开，包括但不仅限于：

第三方代码托管平台（Github、Gitee等）
第三方网盘（百度网盘、阿里网盘等）
第三方网站（CSDN、博客园等）