Skip to content
BranchesTags

Repository files navigation

HaloLight API | Java (Spring Boot)

LicenseJavaSpring BootPostgreSQLMaven

基于 Spring Boot 3.4.1 的企业级后端 API 实现，与 NestJS 版本共用同一数据库（PostgreSQL/Neon）和接口规范，支持 JWT 认证、RBAC 权限、Swagger 文档，为 HaloLight 多框架管理后台提供强大、可扩展的服务端支持。

功能亮点

  • Spring Boot 3.4.1 + Java 23：现代化 Java 框架、依赖注入、注解驱动，企业级稳定性
  • Spring Data JPA + PostgreSQL 16：类型安全的数据库访问、自动建表、关系管理
  • JWT 认证 + RBAC 权限：AccessToken/RefreshToken 双令牌机制，支持角色权限控制
  • Springdoc OpenAPI 文档：自动生成交互式 API 文档，支持在线测试与调试
  • 12 个业务模块：60+ RESTful API 端点，覆盖用户、角色、权限、文档、文件、日历、通知等
  • 企业级架构：分层设计、依赖注入、全局异常处理、请求验证、日志记录
  • 可观测性：Spring Actuator + Micrometer + Prometheus 指标监控
  • 限流与缓存：Bucket4j 限流 + Caffeine 本地缓存
  • Docker 部署：多阶段构建优化、Docker Compose 一键部署、健康检查机制

目录结构

src/main/java/com/halolight/
├── controller/ # REST 控制器层
│ ├── AuthController.java # 认证端点（登录、注册、刷新令牌）
│ ├── UserController.java # 用户管理
│ ├── DashboardController.java # 仪表盘统计
│ └── ... # 其他业务控制器
├── service/ # 业务逻辑层
│ ├── AuthService.java
│ ├── UserService.java
│ └── ...
├── domain/ # 领域层
│ ├── entity/ # JPA 实体（User, Role, Document 等 17 个）
│ │ ├── enums/ # 枚举类型
│ │ └── id/ # 复合主键类
│ └── repository/ # JPA Repository 接口
├── web/dto/ # 数据传输对象（按模块组织）
│ ├── auth/ # 认证相关 DTO
│ ├── calendar/ # 日历相关 DTO
│ └── ...
├── config/ # 配置类
│ ├── SecurityConfig.java # Spring Security 配置
│ ├── CorsConfig.java # CORS 配置
│ ├── OpenApiConfig.java # Swagger 配置
│ ├── CacheConfig.java # Caffeine 缓存配置
│ └── RateLimitConfig.java # 限流配置
├── security/ # 安全组件
│ ├── JwtTokenProvider.java # JWT 生成/验证
│ ├── JwtAuthenticationFilter.java # JWT 认证过滤器
│ └── RateLimitFilter.java # 限流过滤器
├── exception/ # 异常处理
│ └── GlobalExceptionHandler.java # 全局异常处理器
└── HalolightApplication.java # 应用入口
src/main/resources/
├── application.yml # 主配置文件
├── application-dev.yml # 开发环境配置
└── application-prod.yml # 生产环境配置
src/test/ # 测试文件

快速开始

环境要求：JDK >= 23、Maven >= 3.9、PostgreSQL >= 13（或 Neon）。

git clone https://github.com/halolight/halolight-api-java.git
cd halolight-api-java
# 配置环境变量（创建 .env 文件）
cat > .env <<'EOF'DATABASE_URL=jdbc:postgresql://localhost:5432/halolightDATABASE_USERNAME=postgresDATABASE_PASSWORD=postgresJWT_SECRET=your-super-secret-jwt-key-change-in-production-min-32-charsSPRING_PROFILES_ACTIVE=devEOF
mvn spring-boot:run # 本地开发，默认 http://localhost:8000

生产构建与启动

mvn clean package
java -jar target/halolight-api-java-1.0.0.jar

环境变量

变量名说明默认值
SPRING_PROFILES_ACTIVE运行环境dev
PORT服务端口8000
DATABASE_URLPostgreSQL 数据库连接jdbc:postgresql://localhost:5432/halolight
DATABASE_USERNAME数据库用户名postgres
DATABASE_PASSWORD数据库密码postgres
JWT_SECRETJWT 密钥（≥256位）-
JWT_EXPIRATIONAccessToken 过期时间（毫秒）86400000（24小时）
JWT_REFRESH_EXPIRATIONRefreshToken 过期时间（毫秒）604800000（7天）
CORS_ALLOWED_ORIGINSCORS 允许源http://localhost:3000,http://localhost:5173

在项目根目录创建 .env 文件来配置环境变量（支持 spring-dotenv）：

# .env 示例
SPRING_PROFILES_ACTIVE=prod
PORT=8000
DATABASE_URL=jdbc:postgresql://your-host:5432/halolight_db?sslmode=require
DATABASE_USERNAME=your_username
DATABASE_PASSWORD=your_password
JWT_SECRET=your-super-secret-jwt-key-change-in-production-min-32-chars
CORS_ALLOWED_ORIGINS=http://localhost:3000,https://halolight.h7ml.cn

常用脚本

mvn spring-boot:run # 启动开发服务器
mvn clean package # 生产构建，输出到 target/
mvn test# 运行单元测试
mvn test -Dtest=UserServiceTest # 运行指定测试类
mvn verify # 运行测试 + 集成测试
mvn clean test jacoco:report # 生成覆盖率报告

API 模块

项目包含 12 个核心业务模块，提供 60+ RESTful API 端点：

模块端点数描述
Auth7用户认证（登录、注册、刷新 Token、登出、忘记/重置密码）
Users6用户管理（CRUD、分页、搜索、状态更新、改密）
Roles6角色管理（CRUD + 权限分配）
Permissions4权限管理
Teams6团队管理（成员增删、角色更新）
Documents10文档管理（支持标签、分享、移动）
Files10文件管理（上传、下载、收藏、批量操作）
Folders5文件夹管理（树形结构）
Calendar8日历事件管理（参会人、提醒）
Notifications5通知管理
Messages5消息会话
Dashboard5仪表盘统计

📖 在线文档

代码规范

  • 分层架构：Controller → Service → Repository，职责清晰
  • 依赖注入：使用构造器注入（Lombok @RequiredArgsConstructor）
  • DTO 映射：使用 MapStruct 进行实体与 DTO 转换，禁止直接暴露实体
  • 类型安全：严格的 Java 类型系统，确保类型完整性
  • 测试规范：单元测试覆盖核心业务逻辑，集成测试覆盖关键路径
  • 提交规范：遵循 Conventional Commits 规范（feat:, fix:, docs: 等）

可观测性

项目集成 Spring Actuator + Micrometer + Prometheus：

端点说明
/actuator/health健康检查（Liveness/Readiness）
/actuator/metrics应用指标
/actuator/prometheusPrometheus 格式指标
/actuator/info应用信息

部署

Docker Compose（推荐）

# 克隆项目
git clone https://github.com/halolight/halolight-api-java.git
cd halolight-api-java
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置数据库密码、JWT密钥等# 启动所有服务（API + PostgreSQL）
docker-compose up -d
# 查看日志
docker-compose logs -f app
# 停止服务
docker-compose down

Docker 镜像构建

docker build -t halolight-api-java .
docker run -p 8000:8000 --env-file .env halolight-api-java

自托管部署

  1. 环境准备：确保 JDK >= 23 和 Maven >= 3.9 已安装
  2. 配置环境变量：创建 .env 文件并设置必要变量
  3. 构建项目： 
    mvn clean package -DskipTests
  4. 启动服务： 
    java -jar target/halolight-api-java-1.0.0.jar
  5. 进程守护（可选）：使用 systemd 或 Docker 运行

云平台部署

  • AWS：Elastic Beanstalk、ECS 或 EKS
  • GCP：Cloud Run、GKE
  • Azure：App Service、AKS

贡献

欢迎提交 Issue 和 Pull Request 来帮助改进项目！

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'feat: add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

相关链接

许可证

MIT

About

☕ Java 后端 API Backend - Spring Boot 3.4, Spring Security, JWT Auth, RBAC 权限, PostgreSQL, Redis, OpenAPI 文档 → halolight-api-java.h7ml.cn

halolight.docs.h7ml.cn/guide/api-java

Topics

apibackendhalolightjavajwtopenapirbacspring-bootspring-security

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages