Java方法設計原則與實踐：從Effective Java到團隊案例
1.背景
本文通過閱讀《Effective Java》、《Clean Code》、《京東JAVA代碼規范》等代碼質量書籍，結合團隊日常代碼實踐案例進行整理，拋磚引玉、分享一些在編寫高質量代碼方面的見解和經驗。這些書籍提供了豐富的理論知識，而團隊的實際案例則展示了這些原則在實際開發中的應用。希望通過這篇文章，能夠幫助大家更好地理解和運用這些編程最佳實踐，提高代碼質量和開發效率。
2.什么是一個好的方法
在 Java 中，方法是類的一部分，定義了類的行為。方法通常包含方法頭和方法體。方法頭包括訪問修飾符、返回類型、方法名和參數列表，而方法體包含實現方法功能的代碼。
方法的基本結構
[訪問修飾符] [返回類型] [方法名]([參數列表]) {
// 方法體
// 實現方法功能的代碼
}
如果一個方法在滿足業務需求本身的基礎上，職責單一，清晰明了，重點是團隊其他成員可以簡單看懂及維護，這就是一個好的方法。如果只有自己看得懂，其他人看不太懂，則不是一個好的方法。具體原則細節從以下【入參】【方法體】【出參】維度詳細描述
3.入參
1）入參不要太多
理想情況下，方法的參數應盡量少。最佳情況是沒有參數，其次是一個參數，再次是兩個或三個參數，盡量避免超過四個參數。參數越多，方法通常越復雜。從測試的角度來看，編寫各種參數組合的單元測試場景也會變得復雜。
設定四個或更少的參數，因為大多數程序員記不住更長的參數列表。同類型的參數尤其有害，如果不小心弄反了參數的順序，程序可以正常編譯和運行，但結果可能不正確，這極易導致錯誤。
如果方法確實需要多個參數，這通常意味著這些參數應該封裝為一個類，通過創建參數對象來減少參數的數量。
?錯誤案例：重量/體積 同類型參數順序錯誤導致問題
// 錯誤的方法定義，參數過多且容易混淆
public void calculateShippingCost(double weight, double volume, double length,
double width, double height, String destination) {
// 假設這里有計算運費的邏輯
}
// 這里將重量和體積的順序弄反了
service.calculateShippingCost(30.0, 50.0, 10.0, 5.0, 3.0, "New York");
// 實際上應該是：
service.calculateShippingCost(50.0, 30.0, 10.0, 5.0, 3.0, "New York");?正確案例：在這個示例中，由于重量和體積的順序弄反，計算出來的運費會有誤。為了避免這種錯誤，可以將這些參數封裝成一個類：
public class ShippingDetails {
private double weight;
private double volume;
private double length;
private double width;
private double height;
private String destination;
// 構造方法、getter和setter省略
}
// 使用參數對象來簡化方法簽名
public void calculateShippingCost(ShippingDetails details) {
// 假設這里有計算運費的邏輯
}通過將參數封裝成一個類，可以有效減少方法的參數數量，避免參數順序錯誤的問題，提高代碼的可讀性和可維護性。
2）謹慎使用可變參數
可變參數數量，它接受0個或者N個指定類型的參數。可變參數的原理是根據調用位置傳入的參數數量，先創建一個數組，然后將參數放入這個數組中，最后將數值傳遞給該方法。
注意：在對性能要求很高的情況下，使用可變參數要特別小心，每次調用可變參數方法都會導致一次數組的分配和初始化。
?錯誤案例：循環中調用可變參數方法
public class Logger {
// 可變參數方法
public void log(String level, String... messages) {
StringBuilder sb = new StringBuilder();
sb.append(level).append(": ");
for (String message : messages) {
sb.append(message).append(" ");
}
System.out.println(sb.toString());
}
}
// 模擬高頻調用
for (int i = 0; i < 1000000; i++) {
logger.log("INFO", "Message", "number", String.valueOf(i));
}在這個案例中，log方法每次調用都會創建一個新的數組來保存可變參數messages。在高頻調用的場景下，這種數組分配和初始化的開銷會顯著影響性能。
?優化案例：避免可變參數帶來的性能開銷我們使用了List來傳遞日志消息。雖然在每次調用時仍然會創建一個List對象，但相比于每次創建一個數組，這種方式的性能開銷更小，特別是在高頻調用的場景下。
public class Logger {
// 使用List代替可變參數
public void log(String level, List<String> messages) {
StringBuilder sb = new StringBuilder();
sb.append(level).append(": ");
for (String message : messages) {
sb.append(message).append(" ");
}
System.out.println(sb.toString());
}
}
// 模擬高頻調用
for (int i = 0; i < 1000000; i++) {
logger.log("INFO", List.of("Message", "number", String.valueOf(i)));
}?進一步優化：使用StringBuilder直接拼接 在這種情況下，我們完全避免了數組或集合的創建，直接通過StringBuilder拼接字符串，從而最大限度地減少了性能開銷。
public class Logger {
// 使用StringBuilder直接拼接
public void log(String level, String message1, String message2, String message3) {
StringBuilder sb = new StringBuilder();
sb.append(level).append(": ")
.append(message1).append(" ")
.append(message2).append(" ")
.append(message3).append(" ");
System.out.println(sb.toString());
}
}
// 模擬高頻調用
for (int i = 0; i < 1000000; i++) {
logger.log("INFO", "Message", "number", String.valueOf(i));
}如果無法承受上面的性能開銷，但又需要可變參數的便利性，可以有一種兼容的做法，假設方法95%的調用參數不超過3個，那么我們可以聲明該方法的5個重載版本，分別包含（0，1，2，3）個參數和一個（3，可變參數），這樣只有最后一個方法才需要付出創建數組的開銷，而這只占用5%的調用。
?案例：org.slf4j.Logger 每個日志級別都有多個重載的方法，支持不同數量的參數,通過這些方法，SLF4J 提供了靈活且高效的日志記錄接口，可以適應各種不同的日志記錄需求。
package org.slf4j;
public interface Logger {
public boolean isInfoEnabled();
public void info(String msg);
public void info(String format, Object arg);
public void info(String format, Object arg1, Object arg2);
public void info(String format, Object... arguments);
public void info(String msg, Throwable t);
}3）校驗參數的有效性
大部分方法都會對入參的值有一定限制，比如String字符串長度，類型轉換，對象不能為null，訂單運單唯一性，批量接口List個數限制等。首先我們應該在API中詳細描述入參的各種限制條件，并且在方法體的入口進行校驗檢查，以強制實施這些限制。
對參數的檢查，原則是盡早檢查，否則整個鏈路被檢測的可能性降低，并且一旦檢測到，定位起源頭比較復雜。反過來思考，如果不在開頭進行檢查，則可能發生如下情況：方法在接下來鏈路處理過程中拋出錯誤的結果，但方法可能是正常返回，比如接口返回正常，但數據庫保持的時候，由于字段越界導致保存數據庫異常。
參數校驗 應該反應到 技術指標還是業務指標？
- 技術指標：個人理解入參非法不應該體現到UMP技術可用率指標，因為這是API正常的一種體現，如果入參非法不合理，返回上游對應的錯誤碼CODE，本身的技術可用率正常。
- 業務指標：但方法對應的業務指標可以反映入參非法的情況。例如，可以記錄非法入參的次數，以便分析和改進整個鏈路的業務邏輯。
?案例：鏈路校驗一致 比如某個入參，從上游到整個鏈路下游，包括方法內部鏈路，最終到數據庫存儲，校驗規則是一致的。在下面這個例子中，userName的長度限制在方法入口和數據庫存儲過程中保持一致，確保鏈路校驗一致。
public class UserService {
// 用戶信息保存方法
public void saveUser(String userName) {
// 參數校驗
if (userName == null || userName.length() > 20) {
throw new IllegalArgumentException("User name cannot be null and must be less than 20 characters");
}
// 假設數據庫字段長度限制為 20
saveToDatabase(userName);
}
private void saveToDatabase(String userName) {
// 數據庫保存邏輯
// ...
}
}?錯誤案例：鏈路校驗規則不一致 零售C端/B端用戶可以填寫20個字符串，整個鏈路校驗也是20，但底層數據庫是varchar(10)
// 假設數據庫字段長度限制為 10
private void saveToDatabase(String userName) {
// 數據庫保存邏輯
// ...
}探討：鏈路重復校驗
- 比如物流鏈路運單合法性校驗，N個系統都進行校驗是否有必要？是否應該只在入口處校驗，其他鏈路保持信任機制？
4.方法體
1）方法要短小
方法的第一規則是短小，正如行業很多代碼規約，比如阿里規約方法總行數不超過80行，京東代碼規范中方法體的行數不能多于70行，否則降低編碼效率，不方便閱讀和理解。
其實個人理解不用太關注多少行，核心是方法的職責要單一，分清楚方法主干和分支，，看方法里的代碼是否還可以再抽取一個方法，分清代碼個性和共性，把共性的代碼抽取方法，用于復用，讓方法主干更清晰。
2）無副作用
在Java 編程語言中，術語“副作用”(side effects) 指的是一個函數或表達式在計算結果以外對程序狀態（如修改全局變量、改變輸入參數的值、進行I/O 操作等）產生的影響。
?副作用案例：如下filterBusinessType方法的主要作用是返回一個業務類型int類型的值，但它也修改了傳入的response對象的A值作為一個副作用。在外面鏈路使用了A屬性值做邏輯判斷 副作用問題：在filterBusinessType方法中如果是在response之前return了數據，從方法角度看不出問題，但整個鏈路會出現問題。
public int filterBusinessType( Request request,Response response) {
if(...){
return ...
}
boolean flag = isXXX(request, response);
}正如上面說的方法職責單一，只做一件事，但副作用就是一個謊言，方法還會做其他隱藏起來的事情，我們需要理解副作用的存在，并采取合適的策略來管理和控制它們。
如何規避這種現象
為了避免這種情況，可以采用以下幾種策略：
- 分離關注點: 可以將獲取業務類型和響應設置分離成兩個不同的方法。這樣，調用者就可以清晰地看到每個方法的職責。
public int filterBusinessType(String logPrefix,Request request){
// 過濾邏輯...
int businessType=...;
return businessType;
}
public void setResponseData(int filterResult,Response response){
// 根據過濾結果設置響應數據...
response.setFilteredData(...);
}- 返回復合對象（上下文context）: 如果業務類型結果和響應數據是緊密相關的，可以考慮創建一個包含這兩個信息的復合對象，并將其作為方法的返回值。
public FilterResultAndResponse filterBusinessType(String logPrefix,Request request){
// 過濾邏輯...
int result=...;
Response response=new Response();
response.setFilteredData(...);
return new FilterResultAndResponse(result, response);
}
class FilterResultAndResponse{
private int filterResult;
private Response response;
public FilterResultAndResponse(int filterResult,Response response){
this.filterResult = filterResult;
this.response = response;
}
// Getters and setters for filterResult and response}3）控制語句（if/else/while/for等）
不要在條件判斷中執行復雜的語句，將復雜邏輯判斷的結果賦值給一個有意義的布爾變量，以提高可讀性。團隊中也存在很多if語句內的邏輯相當復雜，閱讀者需要分析條件表達式的最終結果，才能明確什么樣的條件執行什么樣的語句。復雜邏輯表達式，與、或、取反混合運算，甚至各種方法縱深調用，理解成本非常高。如果賦值一個非常好理解的布爾變量名字，則是件令人爽心悅目的事情
?錯誤案例：if/else if語句中條件邏輯復雜，并且還存在！取反混合運算，導致這段代碼理解成本比較高
boolean flagA = isKaWhiteFlag(logPrefix, request);
boolean flagB = PlatformTypeEnum.JD_STATION.getValue() == request.getPlatformType();
boolean flagC = KaPromiseUccSwitch.isPopJDDeliverySwitch(request.getDict(),request.getStoreId())
&& (PlatformTypeEnum.JD_STATION.getValue() == request.getPlatformType())
&& (DeliveryTypeEnum.JD_DELIVERY.getType() == request.getDeliveryType());
if (!flagC && flagA) {
......
}else if (!flagB && !flagC &&
StringUtils.isNotBlank(request.getProductCode())
&& kaPromiseSwitch.isKaStoreRouterDs(logPrefix.getLogPrefix(), request.getDict(), request.getStoreId(), request.getCalculateTime(),request.getDeptNo())){
......
}else{
......
}4）異常
4.1）異常應該僅用于異常的情況，不應該用于普通的控制流程
?案例：不當使用異常處理控制流程
// 使用異常處理來控制流程
public static int parseNumber(String number) {
try {
return Integer.parseInt(number);
} catch (NumberFormatException e) {
throw e;
}
}?案例：使用常規控制結構替代異常處理
// 使用常規控制結構來處理正常流程
public static boolean isNumeric(String str) {
if (str == null) {
return false;
}
try {
Integer.parseInt(str);
return true;
} catch (NumberFormatException e) {
return false;
}
}4.2）不要忽略異常
很多代碼都違法了這一條原則，所以本文值得再強調。當方法會拋出一個異常時，就是想要告訴你一些重要信息，所以不要忽略它。忽略它很簡單，catch住，然后里面什么也不做。異常就是強制我們要處理的，空的catch違背了異常的本意，是一種不好的實踐。它不僅違背了異常處理的本意，還可能導致潛在的問題未被發現和解決。
?錯誤案例
try {
// 可能拋出IOException
throw new IOException("File not found");
} catch (IOException e) {
// 空的catch塊，忽略異常
}4.3）異常封裝
對于業務層面的異常，應當進行適當的封裝，定義統一的異常模型。避免直接將底層異常暴露給上層模塊，以保持業務邏輯的清晰性。比如DependencyFailureException：表示服務端依賴的其他服務出現錯誤，服務端是不可用的，可以嘗試重試，類比HTTP的5XX響應狀態碼。InternalFailureException：表示服務端自身出現錯誤，服務端是不可用的，可以嘗試重試，類比HTTP的5XX響應狀態碼。
4.4）異常轉換
1.Web 層絕不應該繼續往上拋異常，因為已經處于頂層，無繼續處理異常的方式，如果意識到這個異常將導致頁面無法正常渲染，那么就應該直接跳轉到友好錯誤頁面，加上友好的錯誤提示信息。
2.開放接口層不能直接拋異常，應該將異常處理成code錯誤碼和錯誤信息message方式返回。其中錯誤碼應該能夠快速識別錯誤的來源，便于團隊成員快速定位問題。同時，錯誤碼應易于比對，有助于團隊對錯誤原因達成共識。其中錯誤編碼可參考HTTP協議的響應狀態碼：
- 2XX（成功響應）：表示操作被成功接收并處理。例如，200表示請求成功。
- 4XX（客戶端錯誤）：表示請求包含語法錯誤或無法完成請求。例如，404表示請求的資源（網頁等）不存在。
- 5XX（服務端錯誤）：表示服務器在處理請求的過程中發生了錯誤。例如，500表示服務器內部錯誤，無法完成請求。
5）日志
5.1）日志三字經：準、懂、少
準：日志打印一定要準確，該打的地方打，不該打的地方不打。如何確定什么地方該打，原則之一看上線后日志是否可以覆蓋方法的所有業務場景
懂：打印日志不只是給你自己看的，更是給團隊其他人看的，所以一定要打印的讓其他人也能看懂，盡量用一些通俗易懂的文字描述讓團隊能看懂
少：少即是多，日志太多第一影響性能，第二存儲成本，第三影響排查
5.2）日志注意事項
1.日志必須有traceId，可追蹤唯一性
2.日志打印建議打中文結合代碼英文字段方法屬性等，確保日志內容清晰、易于理解和分析，否則看完日志還得去看代碼
3.對外API方法出入參必須打印
4.調用其他團隊API（JSF接口、中間件Redis等）同理，必須打印出入參
5.異常信息要打印
6.不用打重復日志，比如在DAO層，由于可能會遇到多種類型的異常，DAO層不需要打印日志。這是因為在Manager或Service層，異常會被再次捕獲并記錄到日志文件中。
7.在 Service 層出現異常時，必須記錄出錯日志到磁盤，其中日志記錄應該遵循一定的規范，包括錯誤碼、異常信息和必要的上下文信息。日志內容應該清晰明了，相當于保護案發現場。
?案例：團隊日志我一直想治理，其中2個痛點：第一個是打印的太多，第二個是很多日志只有當事人能看懂，其他成員看不懂
6）詳細的注釋
詳細的代碼注釋在方法中至關重要，原因如下：
- 業務迭代：隨著業務的不斷迭代，許多方法的意圖變得難以理解。
- 有坑的代碼：團隊中存在非常規、有坑的代碼，增加了維護的難度。
- 人員變更：團隊成員的變動使得代碼的可讀性和可維護性變得更加重要。
方法注釋的要點：
- 描述方法和客戶端之間的約定：注釋應詳細描述方法的功能和其與調用方之間的約定，即方法應該完成什么任務。
- 列出前置條件：注釋應列出所有調用該方法前必須滿足的條件。這可以幫助調用者理解在什么情況下可以安全地調用該方法。
- 列出后置條件：注釋應明確調用方法后哪些條件肯定會成立。這有助于調用者了解調用方法后的預期結果和狀態變化。
描述副作用：如果方法有任何副作用，如啟動后臺線程或修改入參對象的某個值，這些都應該在注釋中詳細說明。這可以幫助調用者預見和處理可能的影響。
public int filterBusinessType( Request request,Response response) {
/** * 切記：return必須在下面這行代碼（isXXX方法）后面，因為外面會使用response.A()來判斷邏輯
* 你可以理解本filterBusinessType方法會返回業務類型，同時如果isXXX方法會修改response.setA(）屬性
*/
boolean flag = isXXX(request, response);
if(...){
return ...
}
}對外API文檔
對于對外的API文檔，注釋應詳細說明每個字段的條件，確保調用方能夠無歧義地理解API的使用。關于API文檔的細節，在此不做詳細討論，但同樣需要強調清晰和詳細的重要性。
通過詳細的注釋，能夠提高代碼的可讀性和可維護性，減少因業務迭代、歷史代碼和人員變更帶來的困擾。
?案例：針對時效內核，代碼比較抽象，添加的詳細注釋詳細，加一下case案例，方便新人可讀性。
?注意點：
- 注釋會撒謊，代碼注釋的時間越久，就離其代碼的本意越遠，越來越變得錯誤，原因很簡單：程序員不能堅持維護注釋。
- 不準確的注釋比沒注釋壞的多，只有代碼能忠實的告訴你告訴你它做的事，那是唯一真正準確的信息來源。
5.出參
返回空的集合或者數組，而不是null
如果方法返回null，而不是空的集合或者數組，那么幾乎所有使用這個方法的地方，都需要特殊判斷null，這樣很容易由于遺忘而出錯。
