技术选型与决策

本文档记录了项目在开发过程中所做的主要技术选型和架构决策，以便团队成员理解其背后的原因。

1. 核心框架与语言

Java 17: 选用 Java 17 是因为它是一个长期支持（LTS）版本，提供了现代化的语言特性（如 Records, Sealed Classes 等），并拥有稳定的生态系统。
Spring Boot 3: 作为业界主流的Java开发框架，Spring Boot 极大地简化了配置和部署，通过其强大的自动配置和依赖管理能力，使我们能快速构建健壮的、生产级的Web服务。
Maven: 作为项目管理和构建工具，Maven 提供了标准的项目结构、强大的依赖管理和一致的构建流程。

RESTful API: 我们选择构建RESTful风格的API，这是当前Web服务的标准实践，具有无状态、易于理解和前后端分离的优点。
DTO (Data Transfer Object): 在Controller层，我们引入了DTO模式（例如 CreateActivityRequest）。
- 决策依据: 将API的请求/响应结构与内部的领域模型（Domain Model）解耦。这样做的好处是：
  1. API稳定性: 内部领域模型的变化不会直接影响外部API的结构。
  2. 安全性: 可以避免意外暴露领域模型中的敏感字段。
  3. 专用性: 可以为特定的API端点定制数据结构，使其更清晰、更高效。
Bean Validation: 通过引入 spring-boot-starter-validation 并在DTO上使用 @Valid 和相关约束注解（如 @NotBlank），我们在Controller层实现了声明式的输入验证。这是一种标准的、非侵入性的验证方式，能保持业务逻辑的纯净。

Flyway: 用于数据库迁移管理。它通过版本化的SQL脚本来管理数据库结构演进，确保了在任何环境下（开发、测试、生产）数据库结构的一致性和可追溯性。
H2 Database (用于测试): H2是一个轻量级的内存数据库，非常适合在单元测试和集成测试中使用。它启动速度快，无需外部依赖，可以确保测试环境的纯净和可重复性。
PostgreSQL (用于生产): 在 pom.xml 中预先定义了依赖。PostgreSQL 是一个功能强大、稳定可靠的开源关系型数据库，适用于生产环境。

API密钥存储: 采用哈希加盐（Salted Hashing）的方式存储API密钥。
- 决策依据: 直接在数据库中存储明文API密钥是极不安全的。通过为每个密钥生成一个唯一的盐（Salt），并将其与密钥组合后进行哈希（SHA-256），我们只存储盐和哈希值。即使数据库被泄露，攻击者也无法直接反推出原始密钥，大大提高了安全性。

自定义异常: 我们创建了业务特定的异常类，如 ActivityNotFoundException 和 ApiKeyNotFoundException。
- 决策依据: 这使得代码的意图更清晰，并且可以利用 @ResponseStatus 注解将特定的业务异常直接映射到HTTP状态码（如 404 Not Found），简化了全局异常处理逻辑。