From b4bc89902d57239217b18a7b5dc5e9290695c92e Mon Sep 17 00:00:00 2001 From: chenpanliang <3245129380@qq.com> Date: Mon, 15 Dec 2025 20:15:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=A0=E9=99=A4=E6=97=A7=E7=9A=84REA?= =?UTF-8?q?DME.md=E6=96=87=E4=BB=B6=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 171 ------------------------------------------------------ 1 file changed, 171 deletions(-) diff --git a/README.md b/README.md index ddaf66c..e69de29 100644 --- a/README.md +++ b/README.md @@ -1,171 +0,0 @@ -# FastAPI项目模板 及 快速开发范式 - - -## 1\. 核心原则 - - * **简洁至上**：避免过度设计。优先选择简单直接的方案。 - * **一致性**：团队成员遵循相同的规范，降低沟通和维护成本。 - * **自动化**：利用工具自动完成格式化、检查等重复性工作。 - ------ - -## 2\. 虚拟环境与依赖管理 - -**目标**：隔离项目依赖，保证环境一致性。 - -**规范**： - - * **工具**：使用 Python 内置的 `venv` 模块。 - - * **创建虚拟环境**：在项目根目录执行 `python -m venv venv`。`.gitignore` 文件应包含 `venv/` 目录。 - * **激活环境**： - * macOS/Linux: `source venv/bin/activate` - * Windows: `.\venv\Scripts\activate` - - * **依赖管理**： - - * 使用 `pip` 和 `requirements.txt` 文件。 - * **安装依赖**：`pip install -r requirements.txt` - * **更新依赖文件**：完成开发或添加新包后，运行 `pip freeze > requirements.txt` 更新依赖列表。或手动修改依赖列表。 - * **(可选) 开发依赖**：可以创建一个 `requirements-dev.txt` 文件，存放仅在开发时使用的工具（如 `pytest`, `black`），并将其 `include` 到主 `requirements.txt` 中或分开安装。 - ------ - -## 3\. 项目结构 - -**目标**：清晰、模块化，便于快速定位代码。 - -推荐一个可扩展的结构： - -``` -your_project_name/ -├── src/                      # 主要应用代码 -│   ├── __init__.py -│   ├── main.py               # FastAPI 应用实例、全局配置、根路由 -│   ├── routers/              # 业务逻辑路由 -│   │   ├── __init__.py -│   │   ├── users.py          # 用户相关的路由 -│   │   └── items.py          # 物品相关的路由 -│   ├── services/             # 业务逻辑层 (当业务复杂时，将复杂逻辑拆分到此处) -│   │   ├── __init__.py -│   │   ├── users.py -│   │   └── items.py -│   ├── models/               # 数据模型 (如 Pydantic 模型) -│   │   ├── __init__.py -│   │   └── user.py           # 用户数据模型 -│   ├── db/                   # 数据库相关配置与连接 -│   │   ├── __init__.py -│   │   └── database.py -│   └── utils/                # 常用工具函数 -│       ├── __init__.py -│       └── tools.py -│ -├── tests/                    # 测试代码 -│   ├── __init__.py -│   └── test_users.py         # 用户模块的测试 -│ -├── .gitignore                # Git 忽略文件 -├── README.md                 # 项目说明文档 -├── requirements.txt          # 项目依赖列表 -├── Dockerfile                # Docker 配置文件 -├── .env.example              # 环境变量文件模板 -└── .env                      # 环境变量文件 (不提交到Git) - -``` - -**说明**: - - * `main.py`: 只做最核心的初始化和包含各个 `router`。 - * `.env`: 存放环境变量，如数据库连接信息、密钥等。 - * `.env.example`: 示例环境变量文件，用于创建 `.env` 文件。 - * `Dockerfile`: Dockerfile 文件，用于构建镜像。 - * `requirements.txt`: 项目依赖文件，用于安装依赖。 - * `README.md`: 项目说明文档。 - * `routers`: 路由模块，存放各个接口的实现。 - * `models`: 模型模块，存放数据库模型定义。 - * `utils`: 工具模块，存放工具函数。 - ------ - -#### 4\. 命名规范 - -**目标**：遵循 PEP 8，保持代码风格统一。 - - * **文件和目录**：使用小写蛇形命名法 (snake\_case)，例如 `user_router.py`。 - * **变量和函数**：使用小写蛇形命名法，例如 `get_user_by_id`, `db_session`。 - * **类和 Pydantic 模型**：使用大驼峰命名法 (PascalCase)，例如 `UserCreate`, `ItemSchema`。 - * **常量**：使用全大写蛇形命名法，例如 `DATABASE_URL`, `API_PREFIX`。 - * **FastAPI 路由函数**：建议以 `动作_资源` 的方式命名，例如 `read_users`, `create_item`。 - ------ - -#### 5\. 编码习惯与最佳实践 - - * **代码格式化**： - - * **强制使用 `black`**。`black` 是一个无妥协的代码格式化工具，能消除所有关于格式的争论。 - * **使用 `isort`** 对 `import` 语句进行排序。 - * 在 CI/CD 或 Git pre-commit hook 中加入自动格式化检查。 - - * **代码质量检查 (Linter)**： - - * 使用 `flake8` 或更现代的 `ruff` 进行代码风格和潜在错误的检查。 - - * **FastAPI 实践**： - - * **善用依赖注入 (`Depends`)**：将数据库会话、用户认证等逻辑通过 `Depends` 注入到路由函数中，实现逻辑复用和解耦。 - * **当router逻辑繁重时，考虑分离功能**：如果路由逻辑过于复杂，考虑将复杂逻辑提取到单独的函数中，放置在service层，并调用。 - * **异步优先**：对于 I/O 密集型操作（如数据库查询、外部 API 请求），始终使用 `async def` 和 `await`。 - * **统一日志输出**：使用 uvcrion 的 `from uvicorn.server import logger` 来捕获特定异常，并返回统一格式的错误响应。例子：`logger.error(f"Error: {e}")` - * **配置管理**：使用 os.getenv("ENV_VAR_NAME", "default_value") 从配置文件和环境变量中加载配置。 - - * **类型提示 (Type Hinting)**： - - * **强制要求**：为所有函数参数和返回值添加类型提示。这是 FastAPI 的核心特性之一，能提供强大的编辑器支持和自动文档生成。 - ------ - -#### 6\. 版本控制 (Git) - - * **分支模型**： - - * `main` (或 `master`) 分支：用于部署的稳定版本。**只接受**来自 `develop` 的合并。 - * `develop` 分支：用于集成各个功能开发的分支。 - * `faet/xxx` 分支：从 `develop` 创建，用于开发新功能。开发完成后合并回 `develop`。 - * `fix/xxx` 分支：用于修复 `main` 分支上的紧急 bug。 - * `dev/xxx` 分支：从 `develop` 创建，用于开发新功能。开发完成后合并回 `develop`。 - - * **Commit Message**： - - * **约定格式**：推荐使用 "Conventional Commits" 规范。 - * `feat: add new user registration endpoint` (新功能) - * `fix: correct password hashing algorithm` (修复 Bug) - * `docs: update README with setup instructions` (文档) - * `style: format code with black` (格式化) - * `refactor: restructure database session handling` (重构) - * `test: add tests for user creation` (测试) - * 这样做的好处是提交历史清晰，便于追溯和自动生成更新日志。 - ------ - -#### 7\. 测试 - - * **框架**：使用 `pytest`。 - * **工具**：结合 FastAPI 的 `TestClient` 和 `HTTPX` 来发送模拟请求。 - * **要求**：核心业务逻辑和重要的 API 端点必须有单元测试或集成测试覆盖。 - * **数据库**：测试时应使用一个独立的测试数据库，并在每次测试前后清理数据。 - ------ - -### 总结 - -这份范式旨在为小型 FastAPI 团队提供一个简单、易于上手的起点。最重要的不是规则本身，而是**团队达成共识并持续遵守**。随着项目和团队的发展，可以随时对这些规范进行调整和补充。 - -**工具链建议**: - - * 虚拟环境: `venv` - * 依赖管理: `pip` + `requirements.txt` - * 代码格式化: `black`, `isort` - * 代码检查: `ruff` (推荐) 或 `flake8` - * 测试: `pytest` - * 版本控制: `Git` \ No newline at end of file