# fastapi

**Repository Path**: liulimi/fastapi

## Basic Information

- **Project Name**: fastapi
- **Description**: FastAPI为微服务而生，基于SpringBoot完成扩展、自动化配置，通过封装一系列Starter来让调用者快速集成组件，降低学习、使用门槛，提高开发效率，点击右上角Star关注项目更新。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://liulimi.com
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 2
- **Created**: 2021-01-06
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI

> 为微服务而生的企业级 Java 快速开发脚手架，开箱即用，生产就绪。

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.3-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Java](https://img.shields.io/badge/Java-25-orange.svg)](https://openjdk.org/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

具体使用说明 [https://gitee.com/liulimi/document](https://gitee.com/liulimi/document) 或
官方文档 [https://www.liulimi.com](https://www.liulimi.com) 了解更多。

---

## 🚀 项目价值

### 核心定位
**为微服务而生的企业级 Java 快速开发脚手架** —— 基于 Spring Boot 4.0 + Java 25，开箱即用的生产级解决方案。

### 技术亮点

| 特性 | 说明 |
|------|------|
| **前沿技术栈** | Spring Boot 4.0.3 + Java 25，拥抱最新生态 |
| **开箱即用** | 内置签名验证、JWT认证、防重放、防重复提交等企业级安全模块 |
| **国密支持** | SM4 加密算法，满足国内安全合规要求 |
| **TOTP 动态口令** | RFC 6238 标准实现，支持 Google Authenticator 等主流验证器 |
| **双令牌机制** | Access Token + Refresh Token，安全与体验兼得 |
| **Prometheus 监控** | 内置 Actuator + Micrometer，运维可观测性完备 |

---

## 📢 核心优势

### 1. 安全先行，生产可用
- ✅ **HMAC-SHA256 签名验证** —— 防篡改、防重放、时效性校验
- ✅ **JWT 双令牌认证** —— 自动刷新、便捷登出、黑名单机制
- ✅ **国密 SM4 加密** —— 敏感数据保护，满足国内合规
- ✅ **XSS 过滤** —— 内置请求过滤与包装
- ✅ **全局异常处理** —— 标准化的错误响应体系
- ✅ **已验证** —— 通过代码审计、渗透测试、压力测试

### 2. 极简接入，注解驱动
```java
@SignAuth      // 签名验证
@JWTAuth       // 登录认证
@RepeatSubmit  // 防重复提交
@ReplayCheck   // 防重放攻击
```
一个注解搞定安全，无需手写拦截器。

### 3. 文档完备，多语言示例
签名验证提供 **JavaScript / Java / Python** 三种客户端实现示例，前端、移动端、后端无缝对接。

### 4. 云原生就绪
- Docker / Podman 一键部署
- 多环境配置（dev/prod）
- 日志、监控、缓存开箱即用

### 5. 高性能设计
- ThreadLocal 缓存 Mac 实例（TOTP 性能优化）
- Redis 缓存层
- 容器优化 + JVM 优化建议

---

## 🎯 适用场景

- **API 网关服务** —— 签名验证 + JWT 认证天然适配
- **微服务架构** —— 轻量、高性能、易扩展
- **开放平台** —— 多租户 AppId 支持，接口安全有保障
- **企业后台** —— TOTP 双因素认证，安全合规
- **物联网 / 游戏服务器** —— 高并发、低延迟设计

---

## 📊 技术栈

```
Spring Boot 4.0.3 | Java 25 | Redis | Prometheus
Hutool | Lombok | Commons-Lang3 | Commons-IO
Docker | Podman | Maven
```

---

## 🎬 快速开始

### Docker / Podman

```shell
docker-compose -f docker-compose.yaml up -d
# 或
podman-compose -f podman-compose.yaml up -d
```

### Maven 构建

```shell
mvn clean package -DskipTests
```

---

## 📖 使用说明

- 基于本项目开发的API，默认为公开接口
- 使用 `@SignAuth` 注解将验证接口签名，实现防篡改、防重放、时效性
- 使用 `@JWTAuth` 注解将会启用认证验证（登陆后使用）

---

## 🔐 安全模块

### 签名验证模块

FastAPI 内置了基于 HMAC-SHA256 的 API 签名验证方案，用于防止请求篡改和重放攻击。

**核心能力：**
- 签名算法：HMAC-SHA256
- 防篡改：参数变更即签名失效
- 防重放：基于 `nonce` + `timestamp` + Redis 实现请求唯一性验证
- 时效性：时间戳验证（默认 60 秒有效期）

详细文档：[./doc/SignAuth.md](./doc/SignAuth.md)

### 认证模块

FastAPI 内置了一套完整的 JWT 认证解决方案，支持令牌生成、刷新、撤销等核心功能。

**核心特性：**
- **双令牌机制**：Access Token（短期）+ Refresh Token（长期）
- **信息隔离**：Refresh Token 使用独立 UUID，非直接使用 Access Token 的 JTI
- **关联验证**：缓存建立 Refresh Token 与 Access Token 的绑定关系
- **自动撤销**：刷新令牌时自动撤销旧令牌
- **便捷登出**：仅需 Access Token，后端自动撤销所有相关令牌

详细文档：[./doc/JWTAuth.md](./doc/JWTAuth.md)

### 虚拟线程性能优化

FastAPI 利用 Java 25 的虚拟线程特性，大幅提升 IO 密集型任务的性能。

**核心优势：**
- **轻量级**：可以创建数百万个虚拟线程，相比平台线程内存消耗极低
- **阻塞友好**：阻塞操作不会占用系统线程资源
- **代码简洁**：编写顺序代码，自动异步执行

**使用示例：**

```java
// 1. 异步执行无返回值任务
AsyncUtil.runAsync(() -> {
    // 清理 Redis 缓存等非关键路径操作
    redisUtil.delete(key);
});

// 2. 异步执行有返回值任务
String result = AsyncUtil.supplyAsync(() -> {
    return fetchDataFromDB();
}, 5, TimeUnit.SECONDS);

// 3. 并发执行多个任务
List<String> results = AsyncUtil.supplyAllAsync(10, TimeUnit.SECONDS,
    () -> fetchFromRedis(),
    () -> fetchFromDB(),
    () -> fetchFromAPI()
);

// 4. 异步日志记录
AsyncLog.info("用户 {} 登录成功", userId);
AsyncLog.error("操作失败", exception);
```

**适用场景：**
- ✅ 数据库查询/更新
- ✅ Redis 缓存读写
- ✅ HTTP API 调用
- ✅ 文件 IO 操作
- ✅ 日志记录等非关键路径操作

**实际应用：**
- `JWTAuthService.revokeToken()` - 异步清理缓存，避免阻塞主流程
- 全局日志记录 - 使用 `AsyncLogUtil` 异步记录，提升响应速度

---

## ⚠️ 全局异常处理

| 异常类型 | 使用场景 | HTTP 状态码 |
|----------|----------|-------------|
| `IllegalArgumentException` | 客户端传参错误（如 code 格式错、appid 无效） | `400 Bad Request` |
| `AuthException` | 认证失败（如 token 无效、未登录） | `401 Unauthorized` |
| `ForbiddenException` | 权限不足（如普通用户访问管理员接口） | `403 Forbidden` |
| `BaseException` | 业务规则拒绝（如"账户已冻结"、"库存不足"） | `500 Internal Server Error` |
| `Exception` / `NullPointerException` | 未预期的系统错误（如 DB 挂了、空指针） | `500 Internal Server Error` |

---

## 🏭 生产可用

我们为组件进行了大量的单元测试以保证逻辑的正确，同时维护了高质量的文档，在 FastAPI 正式对外开放之前，便已经过了：

- ✅ 代码审计
- ✅ 渗透测试
- ✅ 安全检测
- ✅ 性能测试
- ✅ 压力测试

---

## 🤝 参与贡献

FastAPI 是基于 [MIT](http://www.opensource.org/licenses/MIT) 协议发布开源项目，一个开源项目的发展离不开开源社区的力量支持，如果您希望参与 FastAPI 的开发，可以先从 issues 开始，通常来说会有以下的一些步骤：

1. 关注 issues 的动态，评论回复帮助提出疑问的用户
2. Fork 本仓库并新建 Feat_xxx 分支
3. 根据 issues 的内容，找寻根据自己当前对 FastAPI 的了解程度，去修复力所能及的 BUG 或实现功能，并以 Pull Request 的形式提交至仓库
4. 关注自己提交 Pull Request 的进度和状态，以推动您的 Pull Request 尽快合入主仓库
5. 对其他人提交的 Pull Request 进行 Code Review，并给出您的建议和看法
6. 根据他人或自己的需求，研发独立的功能组件
7. 坚持并持续进行上述步骤

---

## 📄 License

[MIT License](LICENSE)

---

<p align="center">
  <b>点击右上角 ⭐ Star 关注项目更新</b>
</p>