From bd6ceffa2f646639c66d47e6bb12728bba51ca7b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=A8=E7=85=9C?= <929216764@qq.com>
Date: Fri, 26 Sep 2025 17:51:32 +0800
Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?=
 =?UTF-8?q?=20/?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ff14ba5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,133 @@
+# CLAUDE.md
+
+此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
+
+## 常用命令
+
+### 运行应用程序
+```bash
+# 安装依赖
+pip install -r requirements.txt
+
+# 1. 直接运行（使用 .env 或默认配置）
+python main.py
+
+# 2. 指定环境运行（推荐）
+ENVIRONMENT=development python main.py  # 使用 .env.dev 配置
+ENVIRONMENT=testing python main.py     # 使用 .env.test 配置
+ENVIRONMENT=production python main.py  # 使用 .env.prod 配置
+
+# 3. Windows 系统设置环境变量
+set ENVIRONMENT=development && python main.py
+set ENVIRONMENT=production && python main.py
+
+# 4. 手动指定 uvicorn 参数（不推荐，应优先使用配置文件）
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+
+# 5. 临时覆盖配置（环境变量优先级最高）
+PORT=9000 HOST=127.0.0.1 python main.py
+
+# 6. 使用便捷启动脚本（推荐）
+python start.py --env dev          # 开发环境
+python start.py --env prod         # 生产环境
+python start.py --port 9000        # 指定端口
+python start.py --env dev --reload # 开发环境+强制热重载
+```
+
+### 配置文件启动说明
+应用会自动读取配置并使用对应的启动参数：
+
+- **开发环境** (`.env.dev`)：自动启用热重载、调试模式、允许所有CORS
+- **测试环境** (`.env.test`)：关闭API文档、严格CORS限制
+- **生产环境** (`.env.prod`)：多worker、关闭热重载、严格安全设置
+
+### 配置管理
+```bash
+# 复制环境配置模板
+cp .env.example .env
+
+# 查看当前配置
+python -c "from app.core.config import settings; print(f'Environment: {settings.ENVIRONMENT}'); print(f'Debug: {settings.DEBUG}')"
+```
+
+### 测试 API
+```bash
+# 访问交互式 API 文档
+# 在浏览器中打开 http://localhost:8000/docs (Swagger UI)
+# 或 http://localhost:8000/redoc (ReDoc)
+
+# 健康检查端点
+curl http://localhost:8000/health
+```
+
+## 架构说明
+
+### 项目结构模式
+这个 FastAPI 演示项目采用分层架构和应用工厂模式，具有清晰的关注点分离：
+
+- **应用工厂** (`app/core/application.py`)：使用工厂模式创建和配置应用实例，集中管理中间件、路由注册和事件处理器。
+
+- **路由聚合** (`app/api/v1/router.py`)：集中管理 v1 版本的所有路由注册，保持主文件精简。
+
+- **API 层** (`app/api/v1/endpoints/`)：处理 HTTP 请求和响应的 FastAPI 路由器。每个路由器对应一个资源（用户、产品）并定义 API 端点。
+
+- **服务层** (`app/services/`)：使用静态服务类实现业务逻辑。目前使用内存中的模拟数据库进行演示。服务处理 CRUD 操作和业务规则。
+
+- **模式层** (`app/schemas/`)：用于请求/响应验证和序列化的 Pydantic 模型。为每个实体遵循 Base、Create、Update 和 Response 模型的模式。
+
+- **模型层** (`app/models/`)：表示核心实体的领域模型。这些是配置了 `from_attributes = True` 的 Pydantic BaseModel，以兼容 ORM。
+
+- **核心配置** (`app/core/config.py`)：使用 pydantic-settings 的集中式设置管理，支持多环境配置文件和环境变量覆盖。
+
+### 关键架构决策
+
+1. **应用工厂模式**：使用 `create_application()` 函数创建应用，便于测试和配置管理，支持多环境部署。
+
+2. **路由模块化**：通过 `router.py` 集中管理路由注册，`main.py` 保持精简，只负责应用启动。
+
+3. **版本化的 API 路由**：所有端点都以 `/api/v1/` 为前缀，便于 API 版本迭代和兼容性管理。
+
+4. **服务模式**：使用单例服务实例（`user_service`、`product_service`）封装所有业务逻辑，保持路由器精简。
+
+5. **模式分离**：为不同操作（Create、Update、Response）设置不同的模式，在 API 设计中提供灵活性，而不暴露内部模型细节。
+
+6. **内存数据存储**：目前使用内存中的模拟列表进行数据存储。这是有意为演示而设计的 - 实际实现将在服务层中集成数据库。
+
+7. **CORS 中间件**：配置了宽松的设置（`allow_origins=["*"]`）适合开发环境。生产环境中应该限制。
+
+8. **事件处理器**：在 `application.py` 中注册启动和关闭事件，便于管理应用生命周期（如数据库连接、缓存初始化等）。
+
+### 配置管理详情
+
+项目采用类似 Spring Boot 的分层配置管理：
+
+1. **配置文件优先级**（从高到低）：
+   - 环境变量
+   - `.env.{environment}` （如 `.env.dev`, `.env.prod`）
+   - `.env` 基础配置文件
+   - 代码中的默认值
+
+2. **多环境配置**：
+   - `.env.dev` - 开发环境：调试开启、允许所有CORS、使用SQLite
+   - `.env.test` - 测试环境：关闭API文档、严格限流、测试数据库
+   - `.env.prod` - 生产环境：关闭调试、使用PostgreSQL、启用监控
+
+3. **配置特性**：
+   - 类型验证和转换
+   - 环境变量解析（如CORS_ORIGINS支持逗号分隔）
+   - 配置验证器（如环境名称校验）
+   - 便利属性（如 `settings.is_development`）
+
+4. **敏感信息管理**：
+   - 密钥、密码等敏感信息通过环境变量管理
+   - `.env` 文件已添加到 `.gitignore`
+   - 提供 `.env.example` 作为配置模板
+
+### 添加新功能
+
+添加新资源/实体时：
+1. 在 `app/models/` 中创建模型
+2. 在 `app/schemas/` 中创建模式（Base、Create、Update、Response）
+3. 在 `app/services/` 中创建包含 CRUD 操作的服务类
+4. 在 `app/api/v1/endpoints/` 中创建包含端点的路由器
+5. 在 `app/api/v1/router.py` 中注册新的路由器，设置适当的前缀和标签
\ No newline at end of file