diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000000000000000000000000000000000000..e4863415d39657a3064d3ac957c28b489ead2436 --- /dev/null +++ b/README.en.md @@ -0,0 +1,84 @@ +# Email Service System + +## Project Overview + +This project is an email service system built on Spring Boot, designed to handle email sending requests. The system features a clear structure and well-modularized design, making it easy to maintain and extend. + +## Key Features + +- Provides REST API endpoints for sending emails +- Supports unified response formats +- Integrates logging and exception handling +- Supports MDC context tracking for enhanced log traceability + +## Technology Stack + +- Spring Boot +- Spring AOP +- SLF4J +- Jackson for JSON processing +- Maven + +## Module Overview + +- `email-front-boot`: Main application module containing the startup class and controllers +- `email-common-core`: Core utilities and common components +- `email-web-common`: Web-related common components, including global exception handler +- `email-dto`: Data Transfer Object module +- `email-service`: Email service interfaces and implementations +- `email-constant`: Constant definitions +- `email-enums`: Enum definitions + +## Core Features + +### Unified Response Format + +The `ResponseDTO` class is used as the return model for all APIs to ensure consistent response formatting. + +### Logging + +AOP-based logging is implemented via the `LoggingAspect` class to automatically record method invocation details before and after controller methods are executed. + +### Exception Handling + +The global exception handler `ControllerErrorAdvice` uniformly processes various exceptions and returns standardized error responses. + +### MDC Tracing + +Supports request chain tracing through `WebTraceFilter` and `MDCTraceUtil` to manage request context trace IDs and span IDs. + +## API Documentation + +### Send Email + +**URL:** `/v1/email/send` + +**Method:** POST + +**Request Body:** `EmailSendDTO` object containing all required information for email sending + +**Response:** `ResponseDTO` object indicating the result of the request processing + +## Configuration Files + +- `application.yml`: Main configuration file +- `application-dev.yml`: Development environment configuration +- `application-test.yml`: Testing environment configuration +- `logback.xml`: Logging configuration + +## How to Run + +1. Ensure Java 8+ and Maven are installed +2. Run the command: `mvn spring-boot:run` + +## Dependency Management + +Dependencies are managed via Maven, with specific dependencies defined in each module’s `pom.xml` file. + +## Logging + +The system uses SLF4J as the logging facade with Logback as the underlying implementation, configured via `logback.xml`. + +## License + +This project is licensed under the Apache 2.0 License. Refer to the license notice in the project files for details. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..6268f195118b155f0c2188afb4209fb28ed4647f --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# 邮件服务系统(Email Service System) + +## 项目简介 + +本项目是一个基于Spring Boot的邮件服务系统,用于处理电子邮件的发送请求。系统结构清晰,模块化设计良好,便于维护和扩展。 + +## 主要功能 + +- 提供REST API接口用于发送电子邮件 +- 支持统一的响应格式 +- 集成日志记录和异常处理 +- 支持MDC上下文跟踪,便于日志追踪 + +## 技术栈 + +- Spring Boot +- Spring AOP +- SLF4J +- Jackson JSON处理 +- Maven + +## 模块说明 + +- `email-front-boot`: 主应用模块,包含启动类和控制器 +- `email-common-core`: 核心工具类和通用组件 +- `email-web-common`: Web相关公共组件,包括全局异常处理器 +- `email-dto`: 数据传输对象模块 +- `email-service`: 邮件服务接口及实现 +- `email-constant`: 常量定义 +- `email-enums`: 枚举定义 + +## 核心特性 + +### 统一响应格式 + +使用`ResponseDTO`类作为所有API的返回模型,确保响应格式一致性。 + +### 日志记录 + +通过`LoggingAspect`类实现AOP日志记录,自动记录控制器方法的调用前后信息。 + +### 异常处理 + +全局异常处理器`ControllerErrorAdvice`统一处理各种异常,返回标准化的错误信息。 + +### MDC跟踪 + +支持请求链路跟踪,通过`WebTraceFilter`和`MDCTraceUtil`实现请求上下文的跟踪ID和跨度ID管理。 + +## 接口文档 + +### 发送邮件 + +**URL:** `/v1/email/send` + +**方法:** POST + +**请求体:** `EmailSendDTO`对象,包含邮件发送所需的所有信息 + +**返回值:** `ResponseDTO`对象,表示请求处理结果 + +## 配置文件 + +- `application.yml`: 主配置文件 +- `application-dev.yml`: 开发环境配置 +- `application-test.yml`: 测试环境配置 +- `logback.xml`: 日志配置 + +## 启动方式 + +1. 确保已安装Java 8+和Maven +2. 执行命令: `mvn spring-boot:run` + +## 依赖管理 + +使用Maven进行依赖管理,具体依赖项在各个模块的`pom.xml`文件中定义。 + +## 日志 + +系统使用SLF4J作为日志门面,具体实现为Logback,配置文件为`logback.xml`。 + +## 许可证 + +本项目遵循Apache 2.0协议,请参阅具体项目文件中的许可证声明。 \ No newline at end of file