1. 写代码不写日志等于裸奔从 System.out 说起1.1 我为什么突然开始认真对待日志先说个场景。之前我写过几个 Java 小项目规模不大代码里到处都是System.out.println()那时候觉得反正能跑输出到控制台看看不就行了。直到有一次写一个文件批处理程序明明本地测试没问题放到服务端一跑就报错更尴尬的是——控制台一旦关掉那点可怜的打印输出就彻底没了。程序跑完到底处理了多少条数据哪一条出了异常全凭运气。从那一刻我开始意识到日志不是一个可选项而是程序运行时的黑匣子。尤其是 Java 这类偏向服务端、长期运行的语言没有日志等于裸奔。出了问题别说排查连复现都无从下手。后来我才明白为什么很多公司的代码规范里第一条就写着禁止用System.out.println打印业务日志。因为它既没有级别又没有时间戳更没有文件输出能力关闭终端就丢失仅适合在本地做临时调试。这一篇日记我就想把日志和 Git 这两块内容完整记录一遍。它们一个负责程序运行时的可见性一个负责代码演化的可追溯性看起来是两件事其实是工程化开发里相辅相成的两条腿。1.2 日志级别不是越多越好而是对应场景刚开始用日志框架的时候我犯过一个典型错误把所有信息都用logger.info()输出甚至循环里面每处理一条数据就 info 一次。结果日志文件一天涨了几个 GB真正出了问题想查也查不过来。后来才认真去理解日志级别的意义。Java 生态里常见级别从低到高大概是TRACE DEBUG INFO WARN ERROR OFF。每个级别对应不同的运行场景TRACE最细粒度的跟踪信息几乎只在开发环境、定位性能问题时打开。DEBUG调试信息用于开发过程中观察变量、流程走向。INFO关键的运行节点信息比如服务启动完成、任务开始、任务结束。WARN有潜在风险但不影响本次运行比如配置项缺失走默认值、重试了三次才成功。ERROR出现异常、操作失败需要人工关注和处理。关键逻辑在于日志系统允许你在不同环境设置不同级别。开发环境设DEBUG测试环境设INFO生产环境设WARN甚至ERROR。这样既保证问题信息不丢失又避免日志量爆炸。这也直接回答了热搜词里那个日志设施到底是什么意思——它是一整套记录、分流、存储、检索日志的基础能力而不只是往控制台打几行字。1.3 从 System.out.println 到日志框架System.out.println最大的问题不是能用不能用而是它背后没有任何工程化设计。想想看你打了十行输出怎么区分哪些是调试过程、哪些是关键节点怎么控制线上环境不打印敏感信息怎么能把日志写到文件里保留三十天这些需求System.out一个都满足不了。Java 自带一个java.util.loggingJUL虽然够用但功能不算强。实际开发中Spring Boot 默认使用 Logback配合 SLF4J 门面接口是当前最主流的组合。SLF4J 只定义接口底层可以选择 Logback、Log4j2 等实现。这样做的好处是业务代码只依赖 SLF4J 的 API底层日志实现想换就换不用改业务逻辑。我当时选 Logback 就一个理由它是 Spring Boot 的默认实现资料多、坑少、配置简单而且和 SLF4J 天然集成。后面我会用一整个章节讲它的实际操作。2. 第一套日志方案Logback 上手实录2.1 引入依赖Maven 里的三行配置如果用的是 Spring Boot 项目其实不需要额外引入 Logbackspring-boot-starter已经自带了。但为了讲清楚原理我还是从最原始的 Maven 依赖开始说。dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.4.14/version /dependency dependency groupIdorg.slf4j/groupId artifactIdslf4j-api/artifactId version2.0.13/version /dependencylogback-classic会自动带上logback-core和slf4j-api所以第二个依赖严格来说可以省略。但写出来有个好处显式声明了版本避免依赖冲突。我曾在某个老项目里因为传递依赖版本不一致出现NoSuchMethodError排查了半天最后发现就是 SLF4J 版本被某个第三方库拉低了。引入依赖之后写代码的感受和System.out.println完全不同import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class UserService { private static final Logger log LoggerFactory.getLogger(UserService.class); public void createUser(String name) { log.info(开始创建用户参数{}, name); // 业务逻辑 log.info(用户创建成功{}, name); } }注意这里用的是占位符{}而不是字符串拼接。我见过很多人一开始不习惯觉得开始创建用户参数 name更直观。但日志框架推荐占位符是有原因的如果当前日志级别不输出这条记录字符串拼接的代码仍然会执行拼接操作白白浪费性能而占位符方式只有在真正需要输出时才会格式化。在循环体或高频方法里这种差异会被明显放大。2.2 logback.xml 最小配置拆解光在代码里调 API 还不够你得给 Logback 一份配置文件。默认情况下它会去 classpath 找logback.xml。给你看一份我项目里最小可用的配置?xml version1.0 encodingUTF-8? configuration !-- 定义控制台输出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appender !-- 定义文件输出 -- appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender filelogs/app.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePatternlogs/app.%d{yyyy-MM-dd}.log/fileNamePattern maxHistory30/maxHistory /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appender root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration这份配置做了四件事定义控制台输出、定义按天滚动的文件输出、设置根日志级别为 INFO、把两个 appender 挂到 root logger 上。这里最值得说的是RollingFileAppender它解决的是日志无限增长的问题。按天滚动每天生成一个文件maxHistory30表示只保留最近三十天过期自动清理。这样日志存储大小是可控的不需要手工去删文件。2.3 输出格式日志不只是打一句话很多人配置日志只关心打到哪不关心打什么内容这是个大误区。日志的每一行信息都应该像一条证据记录能帮你还原当时发生了什么。我个人最推荐的基础 pattern 是这样的%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n逐个解释%d时间戳精确到毫秒。排查问题时时间顺序是关键线索。%thread线程名。配合并发场景你能看出哪个线程在执行哪段逻辑。%-5level日志级别%-5是左对齐占位让输出对齐漂亮。%logger{36}打印日志的类名缩短到 36 个字符以内知道是哪段代码输出的。%msg%n日志消息和换行。除了基础格式Logback 还提供了丰富的扩展能力。热搜词里提到的logback日志堆栈简化就是一个真实需求默认的异常堆栈可能打印出几十行不仅刷屏还经常包含无用的框架内部调用。Logback 的 pattern 里可以用%ex{短长度}控制堆栈深度比如%ex{5}只打印前 5 行核心异常信息配合%xEx还能做去重压缩省空间又不丢关键线索。2.4 踩坑日志文件不生成 / 路径找不到这个坑我印象很深。第一次配置RollingFileAppender我写的是filelogs/app.log/file然后运行程序控制台有输出但目录下怎么也找不到logs文件夹。查了半天才发现Logback 默认情况下不会自动创建不存在的目录。它期望目录已经存在否则就静默失败或者只在特定情况下创建。解决办法是提前手动建好目录或者用logback.xml里判断路径再创建。后来我在项目的启动脚本里加上mkdir -p logs才彻底解决。还有一个更隐蔽的坑文件路径用相对路径logs/app.log时它是相对于进程的工作目录也就是你启动 Java 进程时所在的目录来解析的。如果用 IDE 启动就是当前模块目录如果打 jar 包在服务器上用java -jar app.jar启动那就是你执行命令的那个目录。这就导致本地能生成日志服务器上找不到的诡异现象。后来我习惯把所有日志路径都配置成${LOG_HOME:-logs}这种带环境变量前缀的形式或者直接写绝对路径才没有继续踩。3. 日志是排查问题的第一现场3.1 一次空指针异常从日志到定位的完整链路理论说再多不如看一个真实排查过程。有一次我写一个订单处理接口对端回调的数据结构里有个嵌套字段我在代码里直接取order.getUser().getName()结果抛了空指针。你看日志2024-05-16 14:32:11.087 [http-nio-8080-exec-3] ERROR c.example.OrderService - 处理订单回调失败 java.lang.NullPointerException: null at com.example.OrderService.handleCallback(OrderService.java:147)这行日志就提供了三个关键信息时间14:32:11、线程http-nio-8080-exec-3说明是接口请求线程、代码位置OrderService.java 第147行。有了定位问题基本就解决了一半——是user为 null还是user.getName()里getName()返回 null打开代码一看第 147 行是String name order.getUser().getName();再结合回调文档发现这个接口在某种场景下user字段确实会空缺。如果当时没有日志我可能得在代码里加一堆System.out.println重新部署才能定位到这一行。而有了日志系统线上发生了什么都是留痕的这个问题从发现到定位不超过五分钟。这也是为什么很多公司排查问题时第一句话就是先看日志。3.2 日志该记录什么不该记录什么日志不是越多越好也不是越少越好。我总结了一套适合自己项目的记录准则方法入口和出口记录关键参数和结果尤其是接口层、批量任务这类容易被调用的地方。异常必须记录logger.error(操作失败orderId{}, orderId, e)把异常对象放最后一个参数堆栈才会完整打出来。分支决策点比如走了 A 逻辑还是走了 B 逻辑这种信息在排查业务问题时非常有用。高频循环内谨慎记录比如循环一万次、每次打一条 info日志量会失控。要么降级到 debug要么累计到一定数量再打一批。反过来不该记录的内容也很明确密码、token、身份证号、银行卡号这类敏感信息绝对不能进日志。我见过一个真实事故某个平台的日志里刷出了用户明文密码结果日志文件被导出发到了第三方手里直接变成安全事故。在写日志的时候敏感字段要么不输出要么做脱敏比如密码只显示******手机号只保留前三位后四位。3.3 敏感信息别进日志password 和 token 的教训说到脱敏我分享一个最简单的做法。在实体类的toString()里直接跳过或者打码敏感字段Override public String toString() { return User{id id , username username , password******}; }但更彻底的做法是在统一出口做过滤尤其是项目里用了接口出入参全量打印这类便捷手段的。很多框架支持在序列化层做字段脱敏比如 Jackson 的JsonProperty(access Access.WRITE_ONLY)可以让密码只反序列化不序列化这样即使你把整个对象打出来密码也出不去。这个习惯越早养成越好不然等项目大了再回头清理历史日志里的敏感数据那工作量够你喝一壶的。4. Git 到底在解决什么问题版本控制的本质4.1 没有版本控制的灾难现场日志解决的是程序运行时的可见性而 Git 解决的是代码变更的可追溯性。我刚开始写代码的时候是真的用文件副本管理版本的。项目目录里曾经出现过这种文件名UserService.java UserService_v2.java UserService_final.java UserService_final_v2.java现在回头看这简直是一场灾难。三天后你自己都分不清final_v2和v3哪个才是真正在用的版本。更糟糕的是某天不小心删掉了一段功能代码但你已经想不起是哪个文件里删的、什么时候删的整个项目直接改崩又退不回去。Git 要解决的正是这类问题它可以记录每一次代码的增量变化形成一个不可篡改的历史链你可以随时回退到任意一次提交你可以为实验性改动单独拉分支不影响主干稳定性你还能通过对比差异弄清楚某一行代码是什么时候、因为什么原因改的。4.2 工作区、暂存区、版本库三个概念的直观类比理解 Git 的核心障碍在于暂存区这个概念。你可能会想我明明已经git add了为什么还要git commit这两步到底有什么区别我用的类比是购物车。工作区是你逛超市时手里的购物篮你可以随意把东西放进去新建文件、修改代码这些变化 Git 知道但不记录。暂存区是收银台的结算台你把要买的东西放到结算台上git add这是确认要买的动作但还没付款。git commit就是付款开小票交易完成这一次购买记录被固定下来。如果之后发现买错了你可以看历史小票git log来回退。所以流程永远是修改工作区 →git add放到暂存区 →git commit生成版本记录。4.3 第一个仓库git init 到第一次 commit初始化仓库比想象中简单。在你项目的根目录执行git init这会在当前目录生成一个隐藏的.git文件夹里面装着这个仓库的全部历史和配置。注意一个.git文件夹就是一个独立的仓库它只管理当前目录及其子目录的文件。初始化之后你还需要设置身份信息否则 commit 会失败或者留下错误的作者记录git config --global user.name 你的名字 git config --global user.email 你的邮箱我个人建议--global一次性配置全局身份因为绝大多数情况下你所有项目都是用同一个身份提交的。如果某些项目需要不同身份再去那个仓库里单独设置不带--global的配置覆盖即可。然后就是第一次提交git add . git commit -m 初始化项目用户模块和订单模块git add .会把当前目录下所有新增和修改的文件加入暂存区。但注意这个操作也会把不该提交的文件加进去比如 IDE 配置文件、编译产物等。这就引出了.gitignore的重要性我后面会专门讲。5. 常用 Git 命令和提交规范让历史可读5.1 日常高频命令清单把 Git 用利索其实不需要会一大堆命令高频的就那么几个。我把它们整理成了一张表命令作用使用频率git status查看工作区/暂存区状态每天无数遍git add file把文件加入暂存区每天无数遍git commit -m message生成一次提交每天多次git pull拉取远端更新并合并每天开始工作时git push推送本地提交到远端提交后git log --oneline查看简洁提交历史回溯时git diff查看未暂存的具体改动提交前必看git checkout -- file丢弃工作区某个文件的改动恢复误删时git reset HEAD file把已暂存的文件移出暂存区撤销 add 时有几个命令新手容易搞混git status和git diff。status只告诉你哪些文件变了但不会告诉你具体变了什么diff才是逐行展示改动的。我现在的习惯是每次 commit 之前先git diff看一眼改动再git status看下有没有多加了文件双保险。5.2 分支和合并冲突第一次冲突的完整处理过程分支是 Git 最核心也最让人困惑的能力。简单理解main分支是项目的主线类似定稿的文档你在dev/feature-login分支上开发登录功能类似在草稿上写新段落不会影响定稿。等草稿写好了再把改动合并回主线。创建并切换分支git checkout -b feature-login我刚开始用的时候听到合并分支就觉得很高大上其实常用就两种方式git merge和git rebase。新手建议先从merge开始语义最直观——把两个分支的历史合并成一条线保留分叉痕迹。rebase是把当前分支的提交重放到目标分支之上历史更干净但操作不当容易改写历史建议等对 Git 有更深理解再碰。第一次遇到冲突的时候我当时有点懵Auto-merging UserService.java CONFLICT (content): Merge conflict in UserService.java冲突的本质是两个分支修改了同一个文件的同一行Git 无法自动决定该听谁的。解决办法不是慌而是打开那个文件找到 Git 留下的冲突标记 HEAD private String name 当前分支的版本; private String name 另一个分支的版本; feature-login你需要手工决定保留哪一段或者两段都保留把、、这些标记行删掉然后重新git add、git commit。处理冲突的黄金法则是看不懂的冲突不要乱选去问改了这段代码的人。你可以用git log查看两个分支在这几行的历史提交搞清楚各自改动的意图再决定。5.3 提交信息规范commit message 为什么值得认真写热搜词里赫然有一条git提交规范说明这是所有 Java 开发者绕不开的话题。我见过太多这种提交记录fix bug 修改 提交 ?????这种 commit message 写在当时是明白的过两周回来看基本是天文数字。规范的 commit message 应该让未来的你或同事只看一眼就知道这次改动的含义。目前业界使用最广的规范是 Conventional Commits格式如下type(scope): subject optional bodytype改动类型常见有fix修 bug、feat新功能、refactor重构、docs文档、test测试。scope影响范围比如模块名、服务名可以不写。subject一句话描述用祈使句。举个例子fix(order): 修复订单回调时用户为空导致的空指针异常 feat(user): 新增用户分页查询接口 docs(readme): 更新项目部署说明这种提交信息的好处有两个一是看历史时能快速定位到这次改动是修 bug 还是加功能二是可以基于 type 做自动化的版本号管理和 changelog 生成。很多团队已经在 CI 流程里强制校验 commit message 格式不合法直接拒绝提交。5.4 .gitignore别把 target 和 idea 目录传上去刚开始用 Git 的时候我执行了一次git add .结果把整个target/目录Maven 编译产物和.idea/IDE 配置都提交上去了。后果是仓库里多了一堆无用的二进制文件和历史记录每次构建后git status都会显示一堆文件变更团队协作时还容易产生冲突。正确做法是建一个.gitignore文件把不需要纳入版本控制的内容写进去# 编译产物 target/ *.class # IDE 配置 .idea/ *.iml .vscode/ # 日志文件 logs/ *.log # 操作系统文件 .DS_Store # 环境配置含敏感信息 application-dev.yml.gitignore生效的前提是这些文件还没有被 Git 跟踪过。如果你之前已经git add过那么即使写了.gitignore也不生效需要先执行git rm --cached file把它们从暂存区移除再重新提交一次。6. 日志与 Git 的联动形成自己的开发闭环6.1 改代码前先看日志先复现再动手日志和 Git 看起来是两套独立工具但实际开发中它们可以形成一套完整的闭环。我总结了自己最近半年比较顺手的流程分享给你。第一步遇到线上问题先去查日志。是空指针、超时、还是业务逻辑异常日志里的堆栈信息、时间线、参数值就是问题现场。第二步根据日志定位到出错的代码文件用git log --oneline filename查看这个文件最近的改动历史。这一步特别关键因为很多 bug 是某次改动引入的找到那次提交再看 diff问题原因往往就浮出水面了。6.2 git log 回顾历史从提交信息里找回上下文我举一个前几天刚遇到的例子。有个接口突然变慢了按经验先查日志发现某条 SQL 的时间特别长。然后我执行git log --oneline -5 -- Mapper.xml结果看到一个提交a3f9d21 (refactor): 优化商品列表查询拆分为多条SQL分批执行我大概就有数了——是前几天的重构把原本的一条复杂 SQL 拆成了多条但没处理好 N1 问题导致每次查询多出几十次数据库往返。顺着这个线索再看那次提交的git diff问题就彻底清楚了。这个过程如果没有日志做时间定位、没有 Git 做变更历史回溯基本只能靠猜。这也是为什么 commit message 一定要写清楚。它的价值不是给别人看的而是给未来某个深夜排查问题的自己看的。6.3 一个完整的日常开发工作流把所有东西串起来我现在的工作流长这样开工前git pull拉取最新代码避免基于过期分支开发。新需求拉一个功能分支git checkout -b feature/xxx。开发过程中在关键节点打印日志用DEBUG级别观察流程提交前再决定哪些日志需要保留。写完代码git diff检查改动git status确认没有多余文件。git add相关文件用规范格式 commit。推送分支git push -u origin feature/xxx然后在远程仓库发起合并请求。代码合并后如果线上出现问题先从日志定位再从git log回溯变更。这个流程最大的价值是每一步都有迹可循。日志告诉你程序发生了什么Git 告诉你代码从哪里变成了这样。两者结合你就不会再面对一个报错信息手足无措。7. 学习阶段的体会这两个工具是习惯不是知识最后分享一点我自己的感受。日志和 Git 这类工具难的地方不在于命令记不住或配置不会写而在于把它们变成肌肉记忆。命令忘了可以查文档但遇到问题先看日志、提交前先 diff 一眼、commit message 写明白这些习惯是需要在日常开发中反复练习才能养成的。我学 Git 的时候非常抗拒命令行觉得有图形化工具就够了。后来发现图形化工具虽然直观但命令行才能让你真正理解仓库的内部状态。而且大多数服务器环境是没有图形界面的git status、git log、git diff这几个命令顺手了到哪里都能干活。日志也是同理。一开始可以只用默认配置但至少要养成三个习惯不直接用System.out.println打业务日志异常必须记入日志每次代码改动前先想清楚这里如果出问题日志能不能帮我定位。等这三条成习惯了再去看各种高级用法MDC 链路追踪、日志采集到 ELK、慢查询日志分析自然就不会觉得无从下手。这一期的内容就到这里。日志和 Git 可以说是 Java 入门阶段最枯燥但最值得花时间的两样东西它们不会让你写出更炫酷的业务代码但能让你在代码出问题时不至于一脸茫然。下一篇我打算把日志和 Git 继续往深挖一挖比如多环境日志配置、Git 的 cherry-pick 和 stash 操作都是实际开发里特别实用的技巧。