# api-logging-starter

**Repository Path**: star-lee-lab/api-logging-starter

## Basic Information

- **Project Name**: api-logging-starter
- **Description**: 用于 API 请求/响应日志记录的 Spring Boot Starter
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-23
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# API Logging Starter

一个基于Spring Boot的智能API日志记录starter，可以自动记录HTTP请求和响应的详细信息，支持自定义配置需要记录的请求头。

## 功能特性

- ✅ 自动记录HTTP请求信息（方法、URL、参数、请求体）
- ✅ 自动记录HTTP响应信息（结果、执行时间）
- ✅ 异常信息记录
- ✅ 可配置的请求头记录
- ✅ 支持GET、POST、PUT、DELETE等所有HTTP方法
- ✅ 基于AOP实现，无侵入式集成
- ✅ 完整的YAML配置支持，IDE自动提示

## 快速开始

### 1. 添加依赖
首先，在项目的`pom.xml`中添加 repositories
```xml
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
```
然后，在项目的`pom.xml`中添加依赖：

```xml
<dependency>
    <groupId>com.gitee.star-lee-lab</groupId>
    <artifactId>api-logging-starter</artifactId>
    <version>0.0.1</version>
</dependency>
```

### 2. 基础使用（零配置）

添加依赖后即可使用，默认配置会自动生效：

```java
@RestController
@RequestMapping("/api")
public class UserController {
    
    @GetMapping("/users")
    public List<User> getUsers() {
        // 自动记录请求和响应日志
        return userService.findAll();
    }
    
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        // 自动记录请求体、响应结果等信息
        return userService.save(user);
    }
}
```

### 3. 自定义配置

在`application.yml`中自定义配置：

```yaml
api:
  logging:
    # 需要记录的HTTP请求头列表 可以根据自己项目实际需要进行配置，此处仅为示例
    target-headers:
      - authorization
      - X-Real-IP
      - X-Forwarded-Host
      - X-Forwarded-Port
      - ls-auth
      - os
      - devicename
      - version
      - citycode
```

### 默认值

如果不配置`target-headers`，默认记录空集合，即不记录任何请求头。

## 日志输出示例

### 请求日志示例

```
================  Request Start  ================
===> POST: /api/users
>>> Request Param: {}
>>> Request Body: {"name":"张三","age":25,"email":"zhangsan@example.com"}
===Headers===  authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
===Headers===  X-Real-IP: 192.168.1.100
===Headers===  os: Android
===Headers===  version: 1.2.3
================   Request End   ================
```

### 成功响应日志示例

```
================  Response Start  ================
===Result===  User(id=1, name=张三, age=25, email=zhangsan@example.com)
<=== POST: /api/users(15ms)
================  Response End  ================
```

### 异常响应日志示例

```
================  Response Failed  ================
===Error===  用户已存在
<=== POST: /api/users(8ms)
================  Response Failed  ================
```

## 支持的HTTP方法

本starter自动支持以下注解标记的控制器方法：

- `@GetMapping`
- `@PostMapping`
- `@PutMapping`
- `@DeleteMapping`
- `@RequestMapping`


## 最佳实践

### 1. 生产环境配置建议

```yaml
api:
  logging:
    target-headers:
      - X-Real-IP         # 记录真实IP用于审计
      - authorization     # 记录认证信息（注意安全）
      - version           # 记录客户端版本
```

## 版本更新

### v0.0.1
- 初始版本发布
- 支持基本的请求/响应日志记录
- 支持YAML配置自定义请求头输出到日志

## 技术实现

- **使用Java17**：Java版本
- **基于Spring AOP**：无侵入式实现
- **使用Jackson**：JSON序列化
- **支持Spring Boot 2.x**：广泛兼容
- **自动配置**：开箱即用

## 贡献

欢迎提交Issue和Pull Request来帮助改进这个项目。

## 许可证

Apache License 2.0

## 联系方式

- 项目主页：https://gitee.com/star-lee-lab/api-logging-starter
- 问题反馈：https://gitee.com/star-lee-lab/api-logging-starter/issues

---

**注意**：在生产环境中使用前，请确保了解日志记录可能带来的安全性和性能影响，并根据实际需求进行适当配置。