# web-sdk

**Repository Path**: baichuaniot/web-sdk

## Basic Information

- **Project Name**: web-sdk
- **Description**: web开发工具
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-22
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# web-sdk

web-sdk 是一个 Java Web 开发工具库，提供了审计日志、网关过滤器、Excel 处理、安全认证、响应式编程支持等一系列常用 Web 开发功能。

## 功能特性

### 审计日志
- `@Audit` 注解：用于方法级审计日志记录
- `AuditContext` 接口：审计上下文定义
- `AuditLog` 类：审计日志实体，包含应用名、操作人、IP、请求路径、执行时间等详细信息

### 网关过滤器
- **DebugFilter**：请求/响应调试过滤器，支持 Ant 路径匹配和正则表达式，可记录请求头、请求体、响应头、响应体
- **HeaderAppendAuthorizationFilter**：JWT 认证信息追加到请求头
- **HeaderAppendMemberUidFilter**：JWT 用户 ID 追加到请求头

### Excel 处理
- `@ExcelColumn` 注解：标记 Excel 列映射
- `ExcelReader`：通用的 Excel 读取器，支持自定义验证逻辑
- `ExcelReaderOld`：传统 Excel 读取方式

### 响应式编程支持
- `CachedBodyServerHttpRequest`：可缓存请求体的请求装饰器
- `CachedBodyServerHttpResponse`：可缓存响应体的响应装饰器
- `ClientIP`：获取客户端真实 IP
- `JwtPrincipalArgumentResolver`：JWT 用户信息参数解析器
- `JwtSecurityContextRepository`：JWT 安全上下文仓库
- `Restful`：响应式 RESTful 响应构建

### 安全模块
- `@Authorization` 注解：方法级授权注解
- `JwtCodec`：JWT 编解码接口
- `PasswordEncryption`：密码加密接口
- `Md5Encryption`：MD5 密码加密实现
- `PrincipalPayload`：用户信息载体接口
- `PrincipalCodec`：用户信息编解码接口

### Servlet 支持
- `AuditInterceptor`：审计拦截器
- `AuthorizationInterceptor`：授权拦截器
- `ClientIP`：获取客户端 IP（Servlet 版）
- `Restful`：传统 RESTful 响应构建

### 异常处理
- `BearerTokenException`：Bearer Token 异常
- `BusinessException`：业务异常
- `ForbiddenException`：禁止访问异常
- `NoSuchEntityException`：实体不存在异常
- `AuthenticationException`：认证异常
- `ValidationException`：验证异常

### 工具类
- `BearerToken`：Bearer Token 解析
- `IPv4`：IPv4 地址工具
- `SnowFlake`：雪花算法 ID 生成器
- `ValidationUtils`：验证工具

## 软件架构

项目采用模块化设计，主要包含以下模块：

- `audit` - 审计日志模块
- `error` - 错误异常模块
- `gateway` - Spring Cloud Gateway 过滤器模块
- `io` - Excel 处理模块
- `reactive` - 响应式编程模块
- `security模块
- `` - 安全认证servlet` - Servlet 拦截器模块
- `utils` - 工具类模块
- `validation` - 数据验证模块

## 技术栈

- Java 8+
- Spring Framework
- Spring Cloud Gateway
- Reactor (响应式编程)

## 快速开始

### Maven 依赖

```xml
<dependency>
    <groupId>com.github.baichuan</group<artifactId>webId>
    -sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 使用示例

#### 审计日志

```java
@Audit
public void doSomething() {
    // 业务逻辑
}
```

#### JWT 认证

```java
JwtCodec<PrincipalPayload> codec = new YourJwtCodec();
JwtPrincipalArgumentResolver<PrincipalPayload> resolver = 
    new JwtPrincipalArgumentResolver<>(codec);
```

#### Excel 读取

```java
ExcelReader<User> reader = new ExcelReader<>(inputStream, User.class)
    .validate(row -> {
        // 验证逻辑
        return Result.success(row);
    });

Result<User> result = reader.next();
```

#### 客户端 IP 获取

```java
// Servlet 环境
String ip = ClientIP.get(request);

// 响应式环境
String ip = ClientIP.get(serverHttpRequest);
```

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

本项目遵循 MIT 许可证。