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、博客園等）