
大家好，我是晚安code。
假设一个场景：支付订单批量失败，就一个 NPE，堆栈被吞得干干净净。查了很久，最后发现是第三方回调超时，被中间一层 catch 住悄悄吞掉了。这种锅，八成不是运气差，是 Java 异常与日志规范没立好。
![image](https://developer.qcloudimg.com/http-save/yehe-12591818/9de6444c2a5785009055d2b7d2276e96.webp)这套规范，核心就一句话：**报错要能讲清楚「是谁的错、错在哪、怎么定位」**。本文按错误码、异常处理、日志规约三个维度展开，每条都配正反例，照着抄就行。先点个收藏，我们开始。
## 一、错误码：让每个报错都有「来源」

好的错误码设计，解决的不是"给错误起名字"，而是让任何一个人看到一行报错，十秒内能说清"这是谁的错、错在哪"。
**错误码**：用于标识错误来源与类型的固定编码，由「错误来源 + 数字编号」组成。你可以把它理解成快递单号——拿到单号扫一眼，就知道是哪家快递、哪个环节出了问题。
先说一个我见过的反例。有团队把错误码设计得极其精致，一个码里恨不得塞进模块、等级、场景三层含义，五位数字每位各代表一种意思，美其名曰"结构化"。结果线上报错没人看得懂，排查要先翻半小时文档对照位定义。这就像生僻字字典——字造得越准，越没人随身带着查。所以我把错误码设计原则压成一条：**来源可判断、比对可 equals、语义团队认知一致**。
错误码前一位字母标来源，后四位是数字编号：
![Java 异常与日志规范中错误码 5 位结构：前一位来源 + 后四位编号，来源分 A 用户端 / B 本系统 / C 第三方](https://developer.qcloudimg.com/http-save/yehe-12591818/9636e268652f4ba8f6fae44e450ec51d.png)Java 异常与日志规范中错误码 5 位结构：前一位来源 + 后四位编号，来源分 A 用户端 / B 本系统 / C 第三方- • **A 用户端**：参数传错、支付超时这类"用户那边"的问题；
- • **B 本系统**：业务逻辑出错、程序健壮性不足；
- • **C 第三方**：CDN 故障、消息投递超时。

四位编号从 0001 到 9999，大类之间步长留 100，方便以后插新类别。编号以先到先得的方式在统一平台申请，审批通过就永久固定——别跟业务架构、组织架构挂钩，否则团队一调整，错误码全作废。
几个容易踩的坑，我直接说结论：
- • 一切正常但必须填错误码时，用 **00000** 占位；
- • 错误码不体现版本号和错误等级，等级由日志和释义决定；
- • 别随手造新码，先在已有附表里找语义相近的用；
- • 错误码**不能直接输出给用户**。**错误码（error_code）**、**堆栈（stack_trace）**、**错误信息（error_message）**、**提示信息（user_tip）** 各司其职——错误码给开发看，提示语给用户看，越俎代庖两边都看不懂；
- • 调用第三方出错时，允许转义成 B（本系统），但错误信息里要带上原始第三方错误码，不然找对方对线都没依据。

![错误码第一位字母就是](https://developer.qcloudimg.com/http-save/yehe-12591818/ecc94f17774f277d9de0cf92c6f904f2.png)错误码第一位字母就是"甩锅对象"——A 用户、B 本系统、C 第三方。>**可能有人会问：错误码为什么不直接展示给用户？**
错误码是给开发、运维看的定位标识，直接甩给用户，得到的反馈大概率是"这串数字是啥"。用户需要的是能指导下一步的提示语（比如"订单号不存在，请核对"），错误码 + 堆栈 + 提示语各管一段，才是一套完整的沟通。

## 二、异常处理：该兜的兜住，该暴露的暴露

异常处理的第一原则不是"怎么 catch"，而是**这个错误该不该由我这一层来接**。接得住就接，接不住就往上抛，最怕半吊子——catch 住又不处理，等于把炸弹捂在怀里。
**checked 异常**：编译期强制检查的异常（如 IOException），不处理过不了编译。
**unchecked 异常**：运行时异常（RuntimeException），编译期不查，跑起来才炸。
**NPE**：NullPointerException，空指针异常，Java 里最常见的运行时异常。
Java 异常处理规范里被讨论最多的一条，就是"别拿异常当 if 用"。能预检查的先预检查——NPE、IndexOutOfBoundsException 这类本可以用判空避免，就别用 catch 兜，性能差一个量级不说，还掩盖了真正的逻辑问题：
```

    
    
    
  //&nbsp;正例：预检查
if&nbsp;(obj&nbsp;!=&nbsp;null)&nbsp;{&nbsp;obj.method();&nbsp;}
//&nbsp;反例：拿&nbsp;catch&nbsp;当判断
try&nbsp;{&nbsp;obj.method();&nbsp;}&nbsp;catch&nbsp;(NullPointerException&nbsp;e)&nbsp;{&nbsp;/*&nbsp;静默吞掉&nbsp;*/&nbsp;}
```catch 时要分清稳定代码和非稳定代码。一大段代码包一层 try-catch，出任何问题都走同一个分支，程序没法按不同异常做不同反应，也定位不了问题。正确做法是区分异常类型分别处理——比如用户注册：输入非法字符、用户名已存在、密码太简单，在代码里分门别类判断并给出对应提示。
![Java 异常与日志规范中异常处理决策流程：能预检查就预检查，否则区分类型 catch，不处理就 throws 上抛](https://developer.qcloudimg.com/http-save/yehe-12591818/c978ab7e6edcb2aa242f0f430014d36b.png)Java 异常与日志规范中异常处理决策流程：能预检查就预检查，否则区分类型 catch，不处理就 throws 上抛捕获了就必须处理。不想处理就 throws 抛给调用者，最外层业务使用者必须转成用户能看懂的内容。几个高频坑单独拎出来说：
- • **事务场景**：catch 后要回滚，记得手动回滚事务，别以为框架会替你擦屁股；
- • **finally 块**：关资源要 try-catch 兜住；**不要在 finally 里 return**，它会无情吞掉 try 里的返回值；
- • **catch 类型要匹配**：捕获的异常要么与抛出的一致，要么是它的父类。对方抛绣球你偏伸手接铅球，接不住就砸脸上；
- • **RPC / 二方包 / 反射调用**：用 Throwable 拦截。我踩过一个真坑——二方包版本冲突，运行期抛 NoSuchMethodError，catch 用的却是 Exception，异常往上冒，把一个非核心功能点炸成了核心链路事故。

![image](https://developer.qcloudimg.com/http-save/yehe-12591818/99ec9a655b1d1896ace0ef97ded0ad41.webp)防止 NPE 是调用者的责任，这点写进方法注释说明白。级联调用 `obj.getA().getB().getC()` 最容易炸，JDK8 的 Optional 是现成的护栏：
```

    
    
    
  //&nbsp;级联调用易&nbsp;NPE，用&nbsp;Optional&nbsp;兜底
Optional.ofNullable(user)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.map(User::getAddress)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.map(Address::getCity)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.orElse("未知城市");
```另外两个容易忽略的 NPE 来源：基本类型返回值拆箱（`return Integer` 对象为 null 时自动拆箱炸），以及远程调用返回对象——一律先判空。
![getA().getB().getC() 连点三下，中间断了就是 NPE。](https://developer.qcloudimg.com/http-save/yehe-12591818/5f6a82b73b5f83862fff2de280425bd2.png)getA().getB().getC() 连点三下，中间断了就是 NPE。自定义异常别图省事抛 `new RuntimeException()`，更别抛裸的 `Exception` / `Throwable`，用有业务含义的自定义异常，业界有现成的 `DAOException` / `ServiceException` 直接用。跨应用 RPC 优先用 Result 封装（isSuccess + 错误码 + 简短信息），应用内部推荐异常抛出——抛异常在频繁调用场景下序列化传输损耗不小，这也是我后来才想明白的。
>**可能有人会问：catch Throwable 会不会把 OOM 这种致命错误也吞了？**
会，所以 Throwable 拦截只用在 RPC、二方包、反射这类"编译期对但运行期会变"的场景，捕获后立刻判断并抛出，而不是捂住。Error 类致命错误本来也不该静默处理。

## 三、日志规约：排查问题的唯一线索

日志不是"记录现场"，而是**让三个月后接手的人能看懂现场**。你记录的每条日志，都要对得上"当时发生了什么、为什么这么走"这两个问题。（2026 年 8 月整理，基于 Java 8+ 与 SLF4J 2.x）
**日志门面（SLF4J）**：统一日志 API 的抽象层，底层实现可换成 Logback、Log4j2 而不用改业务代码。你可以理解为"插座"——换电器（实现）不用重新布线。
SLF4J 日志规范的第一条铁律：代码里只依赖 SLF4J / JCL 门面 API，别直接调 Log4j、Logback 的类。字符串拼接用占位符，别用加号——`logger.info("订单 {} 已支付，金额 {}", id, amount)` 只是替换动作，比 StringBuilder append 快得多。trace / debug / info 级日志还要先做开关判断，否则 `debug(getName())` 这种写法每次都会白跑 getName()：
```

    
    
    
  //&nbsp;参数可能拼接开销大，先判断开关
if&nbsp;(logger.isDebugEnabled())&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;logger.debug("当前&nbsp;ID：{}，名称：{}",&nbsp;id,&nbsp;getName());
}
```生产环境日志第一条铁律，是禁 `System.out` / `System.err` / `e.printStackTrace()`。标准输出文件通常要等 Jboss 重启才滚动，量大一点直接把系统文件撑爆。我接手过一个服务，代码里几十处 `System.out.println`，排查问题全靠肉眼盯控制台，改完规范的第一周，磁盘告警就消停了。
![image](https://developer.qcloudimg.com/http-save/yehe-12591818/65327a6763b836e3d9dc335d99983a4c.webp)日志要带上"案发现场 + 异常堆栈"两件套：入参、关键上下文、`e.getMessage()`、异常对象本身，缺一不可。还有个反直觉的坑：**打印日志时别直接拿 JSON 工具把对象转 String**——对象里某个 get 方法被覆写过，打印时可能抛异常，直接让正常业务流程挂掉。要打印就只打业务相关属性，或者调它自己的 toString()。
日志级别怎么选，我做了张表，照着用就行：

        
          
|级别|什么时候用|典型场景|
|:-:|:-:|:-:|
|error|系统逻辑出错、异常、重要故障|异常堆栈、核心链路失败|
|warn|可恢复的异常情况、参数错误|用户输入非法、第三方超时重试|
|info|有选择地记录业务行为|关键流程节点、订单状态流转|
|debug|本地调试，生产禁开|开发期排查逻辑|

        
      最后几条容易被忽略的：日志文件至少留 15 天，涉及网络运行状态、个人敏感信息操作的记录要留不少于六个月并多机备份；敏感信息要脱敏，排查问题用订单号、UUID 这类唯一编号查，别直接打手机号、身份证；日志错误信息优先英文，英文说不清楚再用中文，避免歧义。
![System.out 的纸屑堆满机房，SLF4J 的日志干净一行。](https://developer.qcloudimg.com/http-save/yehe-12591818/0dac60f571932864cc311c65a8663aa9.png)System.out 的纸屑堆满机房，SLF4J 的日志干净一行。说到底，Java 异常与日志规范就一句核心：**错误码定责任，异常定流向，日志定证据**。三者合起来，线上问题从"两小时大海捞针"变成"十分钟精准定位"。这套规范照抄进团队，第一周就能看到效果——前提是 code review 时真的去查，别让规范躺在文档里吃灰。
对新手我的建议是：先别纠结规范全不全，从"catch 不吞异常、日志用占位符、生产禁 println"这三条抓起，就已经赢过一大半项目了。


----
我是晚安code，持续分享编程干货。觉得有用的话记得点赞收藏和关注~也欢迎在评论区聊聊：你的团队是怎么落地 Java 异常与日志规范的？有没有哪条是踩了坑才补上的？

大家好，我是晚安code。假设一个场景：支付订单批量失败，就一个 NPE，堆栈被吞得干干净净。查了很久，最后发现是第三方回调超时，被中间一层 catch 住悄悄吞掉了。这种锅，八成不是运气差，是 Java 异常与日志规范没立好。这套规范，核心就一句话：报错要能讲清楚「是谁的错、错在哪、怎么定位」。本文按错误码、异常处理、日志规约三个维度展开，每条都配正反例，照着抄就行。先点个收藏，我们开始。

Java 异常与日志规范：错误码、异常处理、日志规约一次讲清

Java 异常与日志规范怎么落地？本文从错误码、异常处理、日志规约三个维度，给出一套让线上问题 10 分钟定位的规范，附正反例代码。

编程语言

后端

职业发展

Java异常与日志规范实战指南：错误码定责任、异常定流向、日志定证据。覆盖错误码设计（A/B/C来源分类）、异常处理决策流程（预检查优先、区分catch、Throwable拦截）、SLF4J日志规约（占位符、级别选择、脱敏）。附正反例，助你十分钟定位线上问题。

日志文件

代码解释

短信

JSON

Java

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Java 异常与日志规范：错误码、异常处理、日志规约一次讲清-腾讯云开发者社区-腾讯云

Java 异常与日志规范：错误码、异常处理、日志规约一次讲清

Java 异常与日志规范：错误码、异常处理、日志规约一次讲清

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐