導讀：代碼寫完了，測試也過了，但上線后才是真正考驗的開始。半夜報警電話響起、用戶反饋“頁面白屏”、排查問題如大海撈針……這些場景你是否熟悉？

一個成熟的 Spring Boot 應用，不僅要有強大的業(yè)務邏輯，更必須具備可觀測性（Observability）和健壯性。本文將從結(jié)構(gòu)化日志、全鏈路監(jiān)控、全局異常處理三個維度，手把手教你打造“生產(chǎn)級”的 Spring Boot 應用，讓上線不再是噩夢，而是從容的交付。

一、日志篇：從“亂碼堆”到“數(shù)據(jù)金礦”

很多開發(fā)者的日志習慣是：System.out.println 或者隨意打 logger.info("debug..." + obj)。這在開發(fā)環(huán)境沒問題，但在生產(chǎn)環(huán)境就是災難。

1.1 必須使用結(jié)構(gòu)化日志 (JSON Format)

傳統(tǒng)文本日志難以被機器自動分析。在生產(chǎn)環(huán)境，JSON 格式是標準。

? 最佳實踐：引入 logstash-logback-encoder，將日志輸出為 JSON。

<!-- pom.xml -->
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

<!-- logback-spring.xml -->
<configuration>
    <appender name="JSON_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp/>
                <loggerName/>
                <threadName/>
                <level/>
                <message/>
                <!-- 關鍵：添加追蹤ID，方便鏈路追蹤 -->
                <mdc>
                    <excludeMdcKeyName>traceId</excludeMdcKeyName> 
                </mdc>
                <pattern>
                    <pattern>{"traceId": "%X{traceId}"}</pattern>
                </pattern>
                <stackTrace/>
            </providers>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="JSON_CONSOLE"/>
    </root>
</configuration>

收益：ELK (Elasticsearch, Logstash, Kibana) 或 Loki 可以直接解析字段，支持按 traceId、level、className 快速檢索。

1.2 動態(tài)調(diào)整日志級別 (無需重啟)

生產(chǎn)環(huán)境出現(xiàn) Bug，需要臨時開啟 DEBUG 日志復現(xiàn)問題，難道要重新打包部署？NO！

? 最佳實踐：利用 Spring Boot Actuator 動態(tài)調(diào)整。

<!-- 引入 Actuator -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: loggers # 只暴露日志控制端點，注意安全！
  endpoint:
    loggers:
      enabled: true

操作示例：

# 查看當前級別
curl http://localhost:8080/actuator/loggers/com.example.service

# 動態(tài)調(diào)整為 DEBUG
curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'

1.3 敏感數(shù)據(jù)脫敏

日志中嚴禁出現(xiàn)明文密碼、手機號、身份證、銀行卡號。

? 最佳實踐：自定義 Converter 或使用脫敏工具類。

// 簡單示例：在打印對象前處理
public class SensitiveInfoUtils {
    public static String maskPhone(String phone) {
        if (phone == null) return null;
        return phone.replaceAll("(\d{3})\d{4}(\d{4})", "$1****$2");
    }
}
// 在 toString() 或 JSON 序列化器中調(diào)用

二、監(jiān)控篇：從“黑盒”到“透明玻璃房”

沒有監(jiān)控的系統(tǒng)就是在裸奔。你需要知道：系統(tǒng)活著嗎？慢嗎？錯了嗎？

2.1 核心指標體系 (RED & USE 方法)

• RED (Request, Error, Duration) ：針對微服務接口。

  • Rate (QPS)：每秒請求數(shù)。
  • Error Rate：錯誤率（4xx, 5xx）。
  • Duration：響應時間（P99, P95, Avg）。

• USE (Utilization, Saturation, Errors) ：針對基礎設施。

  • CPU、內(nèi)存、磁盤 IO、網(wǎng)絡帶寬。

2.2 集成 Prometheus + Grafana

Spring Boot Actuator 原生支持 Prometheus。

? 配置步驟：

1. 引入依賴：

   <dependency>
       <groupId>io.micrometer</groupId>
       <artifactId>micrometer-registry-prometheus</artifactId>
   </dependency>

2. 開啟端點：

   management:
     endpoints:
       web:
         exposure:
           include: health,info,prometheus,metrics
     metrics:
       tags:
         application: ${spring.application.name}

3. 自定義業(yè)務指標：

   @Component
   public class CustomMetrics {
       private final Counter orderCounter;
       private final Timer orderTimer;
       public CustomMetrics(MeterRegistry registry) {
           this.orderCounter = Counter.builder("order.created.total")
                   .description("Total orders created")
                   .register(registry);
           this.orderTimer = Timer.builder("order.process.time")
                   .description("Time to process an order")
                   .register(registry);
       }
       public void recordOrder(long timeMs) {
           orderCounter.increment();
           orderTimer.record(timeMs, TimeUnit.MILLISECONDS);
       }
   }

4. 可視化：在 Grafana 中導入 Dashboard ID 6756 (JVM Micrometer) 或自定義面板。

2.3 健康檢查與就緒探針 (K8s 必備)

區(qū)分 Liveness (存活) 和 Readiness (就緒)。

management:
  health:
    livenessState:
      enabled: true
    readinessState:
      enabled: true
  endpoint:
    health:
      probes:
        enabled: true

• /actuator/health/liveness：進程死鎖、OOM 時返回 503，K8s 重啟容器。
• /actuator/health/readiness：依賴（DB, Redis）未連通時返回 503，K8s 不轉(zhuǎn)發(fā)流量。

三、異常處理篇：從“堆棧爆炸”到“友好提示”

直接拋出原始異常給前端是極其不專業(yè)的，既暴露系統(tǒng)細節(jié)，又讓用戶困惑。

3.1 統(tǒng)一全局異常處理器 (@RestControllerAdvice)

? 最佳實踐：定義統(tǒng)一的響應結(jié)構(gòu) Result<T> 和全局處理器。

// 統(tǒng)一響應體
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private Long timestamp;

    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> Result<T> fail(Integer code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }
}

// 全局異常處理器
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 處理業(yè)務異常
    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Result<Void> handleBusinessException(BusinessException e) {
        log.warn("業(yè)務異常：{}", e.getMessage(), e); // 記錄日志，但堆?？蛇x
        return Result.fail(400, e.getMessage());
    }

    // 處理參數(shù)校驗異常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Result<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException e) {
        Map<String, String> errors = new HashMap<>();
        e.getBindingResult().getFieldErrors().forEach(err -> 
            errors.put(err.getField(), err.getDefaultMessage())
        );
        log.warn("參數(shù)校驗失敗：{}", errors);
        return Result.fail(400, "參數(shù)校驗失敗", errors); // 需重載 fail 方法
    }

    // 兜底：處理未知異常
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public Result<Void> handleUnknownException(Exception e, HttpServletRequest request) {
        // 關鍵：記錄完整堆棧和請求上下文
        String traceId = MDC.get("traceId");
        log.error("系統(tǒng)未知異常 [TraceId: {}] [URL: {}]", traceId, request.getRequestURI(), e);
        return Result.fail(500, "系統(tǒng)繁忙，請稍后重試 (Error Code: " + generateErrorCode() + ")");
    }
    
    private String generateErrorCode() {
        return UUID.randomUUID().toString().substring(0, 8);
    }
}

3.2 自定義業(yè)務異常

不要直接用 RuntimeException，要語義化。

public class BusinessException extends RuntimeException {
    public BusinessException(String message) {
        super(message);
    }
    public BusinessException(String message, Throwable cause) {
        super(message, cause);
    }
}

// 使用
if (stock < 0) {
    throw new BusinessException("庫存不足");
}

3.3 異常告警策略

不是所有異常都要打電話報警。

• 忽略：參數(shù)校驗錯誤（400），通常是用戶問題。
• 警告：業(yè)務邏輯錯誤（如庫存不足），記錄日志即可。
• 嚴重：空指針、數(shù)據(jù)庫連接超時、第三方服務不可用（500），立即觸發(fā) PagerDuty/釘釘/企業(yè)微信告警。

技巧：結(jié)合 Sentry 或自研告警系統(tǒng)，對 log.error 進行聚合，同一錯誤 1 分鐘內(nèi)只報一次，防止風暴。

四、進階：鏈路追蹤 (Distributed Tracing)

在微服務架構(gòu)中，一個請求可能經(jīng)過 10 個服務。哪里慢了？哪里錯了？

? 最佳實踐：集成 Micrometer Tracing (Spring Boot 3 默認) + Zipkin/Jaeger/SkyWalking。

1. 引入依賴 (以 Zipkin 為例)：

   <dependency>
       <groupId>io.micrometer</groupId>
       <artifactId>micrometer-tracing-bridge-brave</artifactId>
   </dependency>
   <dependency>
       <groupId>io.zipkin.reporter2</groupId>
       <artifactId>zipkin-reporter-brave</artifactId>
   </dependency>

2. 配置：

   management:
     tracing:
       sampling:
         probability: 1.0 # 生產(chǎn)環(huán)境建議調(diào)低，如 0.1
     zipkin:
       tracing:
         endpoint: http://zipkin-server:9411/api/v2/spans

3. 效果：
   每個請求生成唯一的 traceId，貫穿所有服務和日志。在 Zipkin 界面可以看到完整的調(diào)用拓撲圖和耗時瀑布圖。

五、上線檢查清單 (Checklist)

在點擊“發(fā)布”按鈕前，請確認：

• 日志：是否已切換為 JSON 格式？敏感字段是否脫敏？
• 級別：生產(chǎn)環(huán)境默認是否為 INFO？是否保留了動態(tài)調(diào)整能力？
• 監(jiān)控：Prometheus 是否能抓取到指標？Grafana 大盤是否就緒？
• 健康檢查：/actuator/health 是否正常？K8s 探針是否配置正確？
• 異常：全局處理器是否捕獲了所有 Exception？錯誤碼是否規(guī)范？
• 追蹤：TraceId 是否打印在日志中？鏈路追蹤系統(tǒng)是否連通？
• 告警：關鍵指標（CPU > 80%, Error Rate > 1%）是否配置了告警規(guī)則？

結(jié)語

優(yōu)雅上線不僅僅是把代碼跑起來，而是構(gòu)建一個可觀察、可維護、可信賴的系統(tǒng)。

• 日志是你的眼睛，幫你看見過去；
• 監(jiān)控是你的儀表盤，幫你把握現(xiàn)在；
• 異常處理是你的安全氣囊，幫你抵御意外；
• 鏈路追蹤是你的導航儀，幫你理清復雜關系。

投入時間做好這四點，你將告別“救火式”運維，享受技術帶來的掌控感。

到此這篇關于Spring Boot項目優(yōu)雅上線之日志、監(jiān)控、異常處理最佳實踐指南的文章就介紹到這了,更多相關Spring Boot日志、監(jiān)控、異常處理內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論