# moon-cloud-log

**Repository Path**: SailorMoonKe/moon-cloud-log

## Basic Information

- **Project Name**: moon-cloud-log
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-29
- **Last Updated**: 2025-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Moon Cloud Log

一个基于 Spring Boot 的统一日志记录组件，用于自动记录 HTTP 请求的详细信息。

## 功能特性

- ✅ 自动记录 HTTP 请求和响应信息
- ✅ 支持自定义控制器和方法注解
- ✅ 支持异常信息记录
- ✅ 支持请求头信息记录（可选）
- ✅ 特殊处理 `/error` 路径的错误请求
- ✅ 支持真实IP地址获取
- ✅ 自动记录请求执行状态（success/error）
- ✅ 基于 AOP 切面，性能影响最小
- ✅ 支持 MyBatis Plus，数据持久化到数据库

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.moon.cloud.log</groupId>
    <artifactId>moon-cloud-log</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

### 2. 配置数据库

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_database
    username: your_username
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: assign_id
```

### 3. 创建数据库表

执行 `src/main/resources/sql/request_log.sql` 中的 SQL 脚本。

### 4. 配置日志组件

```yaml
moon:
  cloud:
    log:
      enabled: true                    # 是否启用日志记录
      include-result: true             # 是否记录返回结果
      include-exception: true          # 是否记录异常信息
      include-headers: false           # 是否记录请求头信息
```

### 5. 使用注解

```java
@RestController
@LogController("用户管理")
public class UserController {
    
    @GetMapping("/users")
    @LogMethod("查询用户列表")
    public List<User> getUsers() {
        return userService.findAll();
    }
    
    @PostMapping("/users")
    @LogMethod("创建用户")
    public User createUser(@RequestBody User user) {
        return userService.create(user);
    }
}
```

## 配置提示问题解决

如果在 `application.yml` 中输入 `moon` 时没有自动提示，请按以下步骤解决：

1. **重新构建项目**：
   ```bash
   mvn clean compile install
   ```

2. **刷新 IDE 缓存**：
   - IntelliJ IDEA: File → Invalidate Caches and Restart
   - Eclipse: Project → Clean

3. **检查依赖**：确保项目中包含了 `spring-boot-configuration-processor` 依赖

详细解决方案请参考 [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md)

## 特殊功能

### /error 路径处理

当请求路径为 `/error` 时（通常是 Spring Boot 的错误页面），系统会跳过日志记录，不会在数据库中插入任何记录。这样可以避免错误页面的重复记录，减少数据库存储压力。

### 请求状态记录

系统会自动记录每个请求的执行状态：
- **success**: 请求执行成功，没有抛出异常
- **error**: 请求执行失败，抛出了异常

### 真实IP获取

系统会自动获取客户端的真实IP地址，支持以下场景：
- 直接访问：使用 `request.getRemoteAddr()`
- 代理访问：优先使用 `X-Forwarded-For` 头
- 真实IP：使用 `X-Real-IP` 头

### 请求头记录

通过设置 `include-headers: true` 可以记录所有请求头信息，但请注意：
- 默认关闭，避免记录敏感信息
- 生产环境建议保持关闭状态

## 数据库表结构

```sql
CREATE TABLE `request_log` (
  `request_id` bigint NOT NULL COMMENT '请求ID',
  `server_name` varchar(100) DEFAULT NULL COMMENT '服务名称',
  `request_url` varchar(500) DEFAULT NULL COMMENT '请求路径',
  `request_time` datetime DEFAULT NULL COMMENT '请求时间',
  `request_controller` varchar(100) DEFAULT NULL COMMENT '控制器业务类型',
  `request_method` varchar(10) DEFAULT NULL COMMENT 'HTTP方法',
  `request_operate` varchar(50) DEFAULT NULL COMMENT '操作类型',
  `request_end_time` datetime DEFAULT NULL COMMENT '请求结束时间',
  `request_param` text COMMENT '请求参数',
  `request_result` text COMMENT '返回结果',
  `request_exception` text COMMENT '异常信息',
  `request_ip` varchar(50) DEFAULT NULL COMMENT '请求IP',
  `request_headers` text COMMENT '请求头内容',
  `request_status` varchar(20) DEFAULT NULL COMMENT '请求状态：success/error',
  PRIMARY KEY (`request_id`)
);
```

## 注解说明

### @LogController
用于标记控制器类，指定业务类型：
```java
@LogController("用户管理")
public class UserController {
    // 控制器方法
}
```

### @LogMethod
用于标记方法，指定操作类型：
```java
@LogMethod("创建用户")
public User createUser(@RequestBody User user) {
    // 方法实现
}
```

## 配置属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | boolean | true | 是否启用日志记录 |
| `include-result` | boolean | true | 是否记录返回结果 |
| `include-exception` | boolean | true | 是否记录异常信息 |
| `include-headers` | boolean | false | 是否记录请求头信息 |

## 注意事项

1. 确保项目中包含必要的依赖：
   - Spring Boot Starter Web
   - Spring Boot Starter AOP
   - MyBatis Plus
   - MySQL 驱动

2. 请求头信息记录功能默认关闭，如需启用请设置 `include-headers: true`

3. 文件上传参数会自动标记为"文件"，不会记录具体内容

4. 异常信息会记录异常消息，不会记录完整的堆栈信息

5. 在生产环境中，建议关闭 `include-headers` 以减少存储开销

## 版本历史

### v1.0.0-SNAPSHOT
- 初始版本
- 支持基本的请求日志记录
- 支持自定义注解
- 支持异常处理
- 新增请求IP和请求头记录功能
- 新增 `/error` 路径特殊处理（跳过日志记录）
- 新增请求状态记录功能（success/error）
- 新增常量类，提高代码规范性

## 许可证

MIT License