张翔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+
本地开发
# 克隆项目
git clone <repository-url>
cd everything-is-suitable-api
# 编译项目
mvn clean install
# 启动服务
mvn spring-boot:run -pl everything-is-suitable-gateway
Docker 部署
# 构建和部署所有服务
./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：
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: 生产环境
测试
运行测试
# 运行所有测试
mvn test
# 运行特定模块测试
mvn test -pl everything-is-suitable-common
# 运行特定测试类
mvn test -Dtest=JwtAuthenticationFilterTest
测试覆盖率
# 生成测试覆盖率报告
mvn jacoco:report
# 查看报告
open target/site/jacoco/index.html
性能优化
JVM 优化
-Xms512m -Xmx1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=200
缓存配置
spring:
cache:
type: caffeine
caffeine:
spec: maximumSize=1000,expireAfterWrite=5m
详见 性能测试和优化文档
文档
开发规范
代码风格
- 遵循 Google Java Style Guide
- 使用 Checkstyle 进行代码检查
- 代码覆盖率要求 ≥ 80%
Git 提交规范
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链相关
故障排查
常见问题
-
端口被占用
# 检查端口占用 lsof -i :8080 lsof -i :8081 lsof -i :8082 -
数据库连接失败
- 检查 PostgreSQL 是否启动
- 检查数据库连接配置
- 检查网络连接
-
JWT 认证失败
- 检查 JWT_SECRET 配置
- 检查 Token 格式
- 检查 Token 过期时间
日志查看
# 查看网关日志
docker logs everything-is-suitable-gateway
# 查看客户端应用日志
docker logs everything-is-suitable-client-app
# 查看后台管理应用日志
docker logs everything-is-suitable-admin-app
贡献指南
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'feat: Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件
联系方式
- 项目主页: [GitHub Repository]
- 问题反馈: [Issues]
- 文档: [Wiki]