前言

在现代企业级应用开发中，日志系统扮演着至关重要的角色。无论是问题排查、性能监控，还是业务分析，都离不开完善的日志记录。今天，我们将从零开始，手把手教你构建一个现代化的注解驱动日志框架。

为什么需要自定义日志框架？

现有日志框架的局限性

虽然市面上已有SLF4J、Logback、Log4j2等成熟的日志框架，但它们主要解决的是日志输出的问题，而在实际开发中，我们经常面临以下挑战：

// 传统日志记录方式的痛点
public class UserService {private static final Logger logger = LoggerFactory.getLogger(UserService.class);public User getUserById(Long id) {logger.info("开始查询用户，参数：{}", id);try {User user = userRepository.findById(id);logger.info("查询用户成功，结果：{}", user);return user;} catch (Exception e) {logger.error("查询用户失败，参数：{}，异常：{}", id, e.getMessage(), e);throw e;}}
}

存在的问题：

1. 代码冗余：每个方法都需要重复编写日志代码
2. 侵入性强：业务代码与日志代码紧密耦合
3. 不一致：不同开发者的日志风格差异很大
4. 难维护：修改日志格式需要改动大量代码

注解驱动的优势

我们要构建的框架采用注解驱动的方式，具有以下优势：

// 使用我们的框架后
@Service
public class UserService {@LogMethod(level = LogLevel.INFO, logArgs = true, logResult = true)public User getUserById(Long id) {return userRepository.findById(id);}
}

优势对比：

• ✅ 零侵入：业务代码完全无感知
• ✅ 统一规范：所有日志格式保持一致
• ✅ 灵活配置：通过注解灵活控制日志行为
• ✅ 易于维护：日志逻辑集中管理

技术选型和架构设计

核心技术栈

选型理由：

• Java 17：现代Java特性，记录类型、文本块等
• Spring AOP：成熟的切面编程框架
• Maven：稳定的依赖管理和多模块支持
• 注解：声明式编程，提升开发体验

整体架构设计

我们的框架采用分层模块化设计：

模块职责：

• core模块：核心注解、配置管理、上下文传递
• aop模块：AOP切面实现、方法拦截
• web模块：Web环境集成、HTTP请求追踪
• starter模块：Spring Boot自动配置

项目搭建实战

1. 创建多模块Maven项目

首先创建父项目的POM文件：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.simpleflow</groupId><artifactId>simpleflow-log</artifactId><version>1.0.0-SNAPSHOT</version><packaging>pom</packaging><name>SimpleFlow Log Framework</name><description>基于注解驱动的企业级日志框架</description><properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><!-- 版本管理 --><spring.boot.version>3.2.0</spring.boot.version><spring.version>6.1.0</spring.version><slf4j.version>2.0.9</slf4j.version><junit.version>5.10.0</junit.version></properties><modules><module>simpleflow-log-core</module><module>simpleflow-log-aop</module><module>simpleflow-log-web</module><module>simpleflow-log-spring-boot-starter</module><module>simpleflow-log-samples</module></modules><dependencyManagement><dependencies><!-- Spring Boot BOM --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring.boot.version}</version><type>pom</type><scope>import</scope></dependency><!-- 内部模块依赖 --><dependency><groupId>com.simpleflow</groupId><artifactId>simpleflow-log-core</artifactId><version>${project.version}</version></dependency><dependency><groupId>com.simpleflow</groupId><artifactId>simpleflow-log-aop</artifactId><version>${project.version}</version></dependency></dependencies></dependencyManagement><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><source>17</source><target>17</target></configuration></plugin></plugins></build>
</project>

2. 创建核心模块结构

创建 simpleflow-log-core 模块的POM：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>com.simpleflow</groupId><artifactId>simpleflow-log</artifactId><version>1.0.0-SNAPSHOT</version></parent><artifactId>simpleflow-log-core</artifactId><name>SimpleFlow Log Core</name><description>日志框架核心模块</description><dependencies><!-- 日志API --><dependency><groupId>org.slf4j</groupId><artifactId>slf4j-api</artifactId></dependency><!-- JSON处理 --><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId></dependency><!-- Spring Expression Language --><dependency><groupId>org.springframework</groupId><artifactId>spring-expression</artifactId></dependency><!-- 测试依赖 --><dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId><scope>test</scope></dependency><dependency><groupId>ch.qos.logback</groupId><artifactId>logback-classic</artifactId><scope>test</scope></dependency></dependencies>
</project>

3. 第一个Hello World示例

让我们创建一个简单的示例来验证项目搭建：

// 在 core 模块中创建基础注解
package com.simpleflow.log.annotation;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 日志方法注解 - Hello World版本*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogMethod {/*** 日志消息模板*/String value() default "";
}

创建一个简单的测试用例：

package com.simpleflow.log.annotation;import org.junit.jupiter.api.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;import java.lang.reflect.Method;class LogMethodTest {private static final Logger logger = LoggerFactory.getLogger(LogMethodTest.class);@Testvoid testAnnotationPresent() throws Exception {// 获取测试方法Method method = TestService.class.getMethod("sayHello", String.class);// 检查注解是否存在if (method.isAnnotationPresent(LogMethod.class)) {LogMethod logMethod = method.getAnnotation(LogMethod.class);logger.info("发现日志注解，消息模板：{}", logMethod.value());}}// 测试用的服务类static class TestService {@LogMethod("Hello World - 参数：{}")public String sayHello(String name) {return "Hello, " + name + "!";}}
}

运行和验证

1. 编译项目

# 在项目根目录执行
mvn clean compile

2. 运行测试

mvn test

如果看到类似如下输出，说明项目搭建成功：

[INFO] 发现日志注解，消息模板：Hello World - 参数：{}
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

本章小结

通过本章的学习，我们完成了以下工作：

✅ 完成的任务

1. 理解需求：分析了现有日志框架的局限性
2. 技术选型：确定了Java 17 + Spring + Maven的技术栈
3. 架构设计：设计了分层模块化的项目结构
4. 项目搭建：创建了多模块Maven项目
5. 验证环境：编写并运行了第一个测试用例

🎯 学习要点

• 注解驱动相比传统方式的优势
• 多模块项目的组织方式和依赖管理
• Maven依赖管理的最佳实践
• 分层架构的设计思路

💡 思考题

1. 为什么选择注解而不是配置文件的方式？
2. 多模块项目相比单模块有什么优势？
3. 如何设计一个易于扩展的框架架构？

🚀 下章预告

下一章我们将深入注解的设计，学习如何创建功能强大、易于使用的API接口。我们将设计@LogMethod、@LogClass、@LogIgnore三个核心注解，并探讨注解属性的最佳实践。

---

项目地址：https://github.com/nemoob/atlas-log

💡 小贴士: 建议读者跟着教程一步步实践，只有动手写代码才能真正掌握框架设计的精髓。遇到问题欢迎在评论区讨论！