github-actions-creator/docs/javaspring.md

Java Spring Boot 项目：电子商务 API

概述

使用 Java 和 Spring Boot 构建一个电子商务后端 API，支持商品、订单和用户管理，并集成认证和模拟支付功能。

功能需求

1. 用户模块

• 注册: POST /api/auth/register - 请求体含 username, password, email。密码需 BCrypt 加密。
• 登录: POST /api/auth/login - 返回 JWT。
• 个人资料: GET /api/users/me 和 PUT /api/users/me - 需认证，用于获取和更新用户信息。

2. 商品模块

• 获取商品: GET /api/products - 支持分类、价格筛选、分页和排序。
• 获取商品详情: GET /api/products/{id}。
• 管理员操作: POST, PUT, DELETE /api/admin/products - 需 ROLE_ADMIN 权限，用于增/改/删商品。

3. 订单模块

• 创建订单: POST /api/orders - 需认证。请求体含商品列表和收货地址。
• 获取订单历史: GET /api/orders - 需认证，返回当前用户的所有订单。
• 获取订单详情: GET /api/orders/{id} - 需认证，只能查看自己的订单。
• 更新订单状态: PUT /api/admin/orders/{id}/status - 需 ROLE_ADMIN 权限，更新状态为 SHIPPED, DELIVERED 等。

4. 支付 (模拟)

• 处理支付: POST /api/orders/{id}/pay - 需认证，模拟支付流程，成功后更新订单状态为 PAID。

技术栈

• 语言: Java 17+
• 框架: Spring Boot 3.x
• 数据库: PostgreSQL 或 MySQL
• 持久化: Spring Data JPA
• 认证: Spring Security (JWT)
• 校验: Spring Validation
• API文档: SpringDoc (OpenAPI 3)
• 构建: Maven 或 Gradle

项目结构 (Maven)

/ecommerce-api
└── src/main/
    ├── java/com/example/ecommerce/
    │   ├── Application.java        # 启动类
    │   ├── config                  # SecurityConfig 等
    │   ├── controller              # API 控制器
    │   ├── dto                     # 数据传输对象
    │   ├── entity                  # JPA 实体
    │   ├── repository              # JPA 仓库
    │   ├── service                 # 业务服务
    │   └── exception               # 异常处理
    └── resources/
        └── application.properties  # 配置文件

任务步骤

1. 初始化: 使用 Spring Initializr 创建项目，包含 Web, JPA, Security 等依赖。
2. 数据库配置: 在 application.properties 中配置数据源和 JPA。
3. 实体建模: 创建 User, Product, Order 等 JPA 实体。
4. 仓库接口: 创建继承自 JpaRepository 的接口。
5. 安全配置: 配置 SecurityConfig，设置密码编码器、JWT 过滤器和端点访问权限。
6. DTOs与控制器: 创建 DTO 并编写 Controller 处理 HTTP 请求。
7. 业务服务: 在 Service 层实现核心业务逻辑。
8. 异常处理: 创建全局异常处理器。
9. API文档: 使用 SpringDoc 注解生成 OpenAPI 文档。
10. 测试: 使用 JUnit 5 和 Mockito 编写单元和集成测试。

先行任务: 设计详细的 API 端点和数据模型，并整理成文档。