张翔
277 lines
5.7 KiB
Markdown
277 lines
5.7 KiB
Markdown
# Everything Is Suitable API
|
|
|
|
基于 Spring Boot 3.x 和响应式编程的命理分析 API 系统，采用双应用架构设计。
|
|
|
|
## 项目概述
|
|
|
|
本项目是一个完整的命理分析服务平台，支持：
|
|
- 客户端用户命理查询
|
|
- 后台管理系统
|
|
- 用户认证和授权
|
|
- 数据统计分析
|
|
|
|
## 架构设计
|
|
|
|
### 双应用架构
|
|
|
|
项目采用双应用架构，将客户端应用和后台管理应用分离：
|
|
|
|
```
|
|
Gateway (8080) → Client App (8081)
|
|
→ Admin App (8082)
|
|
→ PostgreSQL
|
|
```
|
|
|
|
**优势**:
|
|
- 独立部署和运维
|
|
- 灵活的扩展能力
|
|
- 统一的认证和授权
|
|
- 高性能的响应式架构
|
|
|
|
### 技术栈
|
|
|
|
- **框架**: Spring Boot 3.5.10
|
|
- **响应式**: Spring WebFlux + R2DBC
|
|
- **网关**: Spring Cloud Gateway
|
|
- **认证**: JWT
|
|
- **授权**: RBAC
|
|
- **缓存**: Caffeine
|
|
- **数据库**: PostgreSQL 16
|
|
- **容器化**: Docker + Docker Compose
|
|
|
|
## 模块说明
|
|
|
|
### 应用模块
|
|
- `everything-is-suitable-client-app`: 客户端应用 (8081)
|
|
- `everything-is-suitable-admin-app`: 后台管理应用 (8082)
|
|
- `everything-is-suitable-gateway`: 网关 (8080)
|
|
|
|
### 接口层模块
|
|
- `everything-is-suitable-client-api`: 客户端接口层
|
|
- `everything-is-suitable-admin-api`: 后台管理接口层
|
|
|
|
### 业务模块
|
|
- `everything-is-suitable-biz`: 命理分析业务逻辑
|
|
- `everything-is-suitable-client`: 客户端核心功能
|
|
- `everything-is-suitable-sys`: 系统管理
|
|
- `everything-is-suitable-statistics`: 统计分析
|
|
|
|
### 公共模块
|
|
- `everything-is-suitable-common`: 公共组件和工具类
|
|
- `everything-is-suitable-db`: 数据库访问层
|
|
|
|
## 快速开始
|
|
|
|
### 前置要求
|
|
|
|
- JDK 21+
|
|
- Maven 3.8+
|
|
- Docker 20.10+
|
|
- Docker Compose 2.0+
|
|
|
|
### 本地开发
|
|
|
|
```bash
|
|
# 克隆项目
|
|
git clone <repository-url>
|
|
cd everything-is-suitable-api
|
|
|
|
# 编译项目
|
|
mvn clean install
|
|
|
|
# 启动服务
|
|
mvn spring-boot:run -pl everything-is-suitable-gateway
|
|
```
|
|
|
|
### Docker 部署
|
|
|
|
```bash
|
|
# 构建和部署所有服务
|
|
./build-and-deploy.sh
|
|
|
|
# 停止所有服务
|
|
./stop-services.sh
|
|
|
|
# 查看服务状态
|
|
docker-compose ps
|
|
|
|
# 查看服务日志
|
|
docker-compose logs -f
|
|
```
|
|
|
|
## API 端点
|
|
|
|
### 网关端点
|
|
- `http://localhost:8080/api/auth/login`: 用户登录
|
|
- `http://localhost:8080/api/auth/register`: 用户注册
|
|
- `http://localhost:8080/api/fortune/daily`: 每日命理
|
|
- `http://localhost:8080/api/fortune/monthly`: 每月命理
|
|
- `http://localhost:8080/api/fortune/yearly`: 每年命理
|
|
|
|
### 后台管理端点
|
|
- `http://localhost:8080/api/admin/users`: 用户管理
|
|
- `http://localhost:8080/api/admin/statistics`: 统计数据
|
|
|
|
### 监控端点
|
|
- `http://localhost:8080/actuator/health`: 健康检查
|
|
- `http://localhost:8080/actuator/metrics`: 性能指标
|
|
|
|
## 认证和授权
|
|
|
|
### JWT 认证
|
|
|
|
所有需要认证的端点都需要在请求头中提供 JWT Token：
|
|
|
|
```bash
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
### RBAC 权限
|
|
|
|
后台管理端点需要相应的权限：
|
|
|
|
| 角色 | 权限 |
|
|
|------|--------|
|
|
| ADMIN | 所有权限 |
|
|
| MANAGER | 读取权限 |
|
|
| OPERATOR | 基础权限 |
|
|
|
|
## 配置说明
|
|
|
|
### 环境变量
|
|
|
|
| 变量 | 说明 | 默认值 |
|
|
|------|------|---------|
|
|
| JWT_SECRET | JWT 密钥 | this-is-a-secure-jwt-secret-key... |
|
|
| JWT_EXPIRATION | JWT 过期时间 (ms) | 86400000 |
|
|
| SPRING_PROFILES_ACTIVE | Spring Profile | dev |
|
|
| SPRING_DATASOURCE_URL | 数据库 URL | r2dbc:postgresql://localhost:5432/everything_is_suitable |
|
|
| SPRING_DATASOURCE_USERNAME | 数据库用户名 | postgres |
|
|
| SPRING_DATASOURCE_PASSWORD | 数据库密码 | postgres |
|
|
|
|
### Profile 配置
|
|
|
|
- `dev`: 开发环境
|
|
- `prod`: 生产环境
|
|
|
|
## 测试
|
|
|
|
### 运行测试
|
|
|
|
```bash
|
|
# 运行所有测试
|
|
mvn test
|
|
|
|
# 运行特定模块测试
|
|
mvn test -pl everything-is-suitable-common
|
|
|
|
# 运行特定测试类
|
|
mvn test -Dtest=JwtAuthenticationFilterTest
|
|
```
|
|
|
|
### 测试覆盖率
|
|
|
|
```bash
|
|
# 生成测试覆盖率报告
|
|
mvn jacoco:report
|
|
|
|
# 查看报告
|
|
open target/site/jacoco/index.html
|
|
```
|
|
|
|
## 性能优化
|
|
|
|
### JVM 优化
|
|
|
|
```bash
|
|
-Xms512m -Xmx1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=200
|
|
```
|
|
|
|
### 缓存配置
|
|
|
|
```yaml
|
|
spring:
|
|
cache:
|
|
type: caffeine
|
|
caffeine:
|
|
spec: maximumSize=1000,expireAfterWrite=5m
|
|
```
|
|
|
|
详见 [性能测试和优化文档](./docs/performance-testing-and-optimization.md)
|
|
|
|
## 文档
|
|
|
|
- [双应用架构文档](./docs/dual-app-architecture.md)
|
|
- [性能测试和优化](./docs/performance-testing-and-optimization.md)
|
|
- [实施计划](./docs/plans/2025-02-24-dual-app-architecture-refactor.md)
|
|
|
|
## 开发规范
|
|
|
|
### 代码风格
|
|
- 遵循 Google Java Style Guide
|
|
- 使用 Checkstyle 进行代码检查
|
|
- 代码覆盖率要求 ≥ 80%
|
|
|
|
### Git 提交规范
|
|
```
|
|
feat: 新功能
|
|
fix: 修复 bug
|
|
docs: 文档更新
|
|
style: 代码格式调整
|
|
refactor: 重构
|
|
test: 测试相关
|
|
chore: 构建/工具链相关
|
|
```
|
|
|
|
## 故障排查
|
|
|
|
### 常见问题
|
|
|
|
1. **端口被占用**
|
|
```bash
|
|
# 检查端口占用
|
|
lsof -i :8080
|
|
lsof -i :8081
|
|
lsof -i :8082
|
|
```
|
|
|
|
2. **数据库连接失败**
|
|
- 检查 PostgreSQL 是否启动
|
|
- 检查数据库连接配置
|
|
- 检查网络连接
|
|
|
|
3. **JWT 认证失败**
|
|
- 检查 JWT_SECRET 配置
|
|
- 检查 Token 格式
|
|
- 检查 Token 过期时间
|
|
|
|
### 日志查看
|
|
|
|
```bash
|
|
# 查看网关日志
|
|
docker logs everything-is-suitable-gateway
|
|
|
|
# 查看客户端应用日志
|
|
docker logs everything-is-suitable-client-app
|
|
|
|
# 查看后台管理应用日志
|
|
docker logs everything-is-suitable-admin-app
|
|
```
|
|
|
|
## 贡献指南
|
|
|
|
1. Fork 项目
|
|
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
|
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
|
|
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
|
5. 创建 Pull Request
|
|
|
|
## 许可证
|
|
|
|
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
|
|
|
|
## 联系方式
|
|
|
|
- 项目主页: [GitHub Repository]
|
|
- 问题反馈: [Issues]
|
|
- 文档: [Wiki] |