{"id":31786263,"url":"https://github.com/mautops/faster-app","last_synced_at":"2025-10-10T12:50:50.412Z","repository":{"id":313849560,"uuid":"1053121705","full_name":"mautops/faster-app","owner":"mautops","description":"API  app with FastAPI","archived":false,"fork":false,"pushed_at":"2025-09-22T08:15:40.000Z","size":1472,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T10:19:23.378Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mautops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T02:51:45.000Z","updated_at":"2025-09-22T08:15:43.000Z","dependencies_parsed_at":"2025-09-09T06:33:59.139Z","dependency_job_id":"aeabdbe7-fe7e-40c1-a846-0287f1c155e0","html_url":"https://github.com/mautops/faster-app","commit_stats":null,"previous_names":["mautops/faster-app"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mautops/faster-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautops%2Ffaster-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautops%2Ffaster-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautops%2Ffaster-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautops%2Ffaster-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mautops","download_url":"https://codeload.github.com/mautops/faster-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautops%2Ffaster-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003890,"owners_count":26083641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T12:50:47.372Z","updated_at":"2025-10-10T12:50:50.404Z","avatar_url":"https://github.com/mautops.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🚀 Faster APP\n\n**FastAPI 最佳实践框架 - 约定优于配置**\n\n[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.116+-green.svg)](https://fastapi.tiangolo.com)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.0.35-orange.svg)](https://github.com/mautops/faster-app)\n\n_为 FastAPI 带来 Django 风格的项目结构和开发体验_\n\n[快速开始](#-快速开始) • [命令行工具](#️-命令行工具详解) • [社区支持](#-社区与支持) • [许可证](#-许可证)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 解决什么问题？\n\n### 💭 FastAPI 的灵活性困扰\n\nFastAPI 非常灵活，但这种灵活性也带来了问题：\n\n| 问题             | 表现                               | 影响                       |\n| ---------------- | ---------------------------------- | -------------------------- |\n| **项目结构混乱** | 每个项目都有不同的目录结构         | 团队协作困难，代码难以维护 |\n| **重复造轮子**   | 每次都要重新设计模型基类、路由结构 | 开发效率低，代码质量不一致 |\n| **配置复杂**     | 手动注册路由、中间件、数据库模型   | 容易出错，启动代码冗长     |\n| **缺乏约定**     | 没有统一的开发规范和最佳实践       | 新人上手困难，项目难以扩展 |\n\n\u003e ### 💡 Faster APP 的解决方案\n\n**核心理念：约定优于配置 (Convention over Configuration)**\n\n借鉴 Django 的成功经验，为 FastAPI 制定一套标准化的项目结构和开发约定。\n\n---\n\n## ✨ 核心特性\n\n### 🏗️ 标准化项目结构\n\n```\nyour-project/\n├── apps/                    # 应用模块 (Django 风格)\n│   ├── users/              # 用户模块\n│   │   ├── models.py       # 数据模型\n│   │   ├── routes.py       # API 路由\n│   │   └── commands.py     # 命令行工具\n│   └── posts/              # 文章模块\n│       ├── models.py\n│       ├── routes.py\n│       └── commands.py\n├── config/                 # 配置目录\n│   └── settings.py         # 自定义配置\n└── .env                    # 环境变量\n```\n\n### 🔍 智能发现与注册\n\n\u003e 通过智能自动发现，实现项目 0️⃣ 配置启动\n\n#### 🛣️ 路由自动发现\n\n扫描 `apps/*/*.py` 文件，递归查找 `APIRouter` 类的实例，并注册成为 Fastapi 路由\n\n#### 📊 模型自动发现\n\n扫描 `apps/*/models.py` 文件，递归查找 `tortoise.Model` 类，并注册到 TORTOISE_ORM 中，实现模型自动化管理\n\n#### ⚡ 命令自动发现\n\n扫描 `apps/*/*.py` 文件，递归查找 `BaseCommand` 类实例，注册给 Fire 库，实现命令行参数管理\n\n#### 🔧 中间件自动发现\n\n扫描 `apps/middleware/*.py` 文件，递归查找 `BaseMiddleware` 类，然后注册到 fastapi 实例，实现中间件注册\n\n#### ⚙️ 项目配置自动发现\n\n扫描 `apps/config/*.py` 文件，递归查找 `BaseSettings` 类实例，自动合并多个配置类，从 `.env` 中读取配置并注册给应用；\n\n### 🗄️ 企业级模型基类\n\n```python\n# 四大基础模型，覆盖 90% 业务场景\nUUIDModel     # UUID 主键\nDateTimeModel # 创建/更新时间\nStatusModel   # 状态管理 (启用/禁用)\nScopeModel    # 多租户作用域\n```\n\n### 🛠️ Django 风格命令行\n\n```bash\nfaster server start    # 启动开发服务器\nfaster db migrate      # 数据库迁移\nfaster db upgrade      # 执行迁移\n```\n\n---\n\n## 🚀 快速开始\n\n### 📦 初始化 uv 项目\n\n```\n# 初始化 uv 项目, python 版本 \u003e= 3.11\n\nuv init demo\ncd demo\nuv add faster-app\n\n# 移除项目目录下的 main.py 文件\nrm -rf main.py\n\n# 恭喜你，此时可以直接执行如下命令启动项目\nfaster server start\n\n# 不过此时仍然没有任何业务功能而已\n```\n\n### ⚡ 使用内置命令加速开发\n\n```shell\n# 创建 demo 项目\nfaster app demo\n\n# 创建自定义配置\nfaster app config\n\n# 创建自定义基础环境\nfaster app env\n```\n\n### 🗄️ 执行数据库操作\n\n```shell\n# 初始化数据库配置\nfaster db init\n\n# 初始化项目配置到数据库\nfaster db init_db\n```\n\n## 🛠️ 命令行工具详解\n\nFaster APP 提供了完整的 Django 风格命令行工具，基于 [Fire](https://github.com/google/python-fire) 库实现，支持自动发现和注册。\n\n### 📋 命令概览\n\n| 命令组          | 说明       | 主要功能                 |\n| --------------- | ---------- | ------------------------ |\n| `faster app`    | 应用管理   | 创建项目结构、配置文件等 |\n| `faster db`     | 数据库管理 | 数据库迁移、初始化等操作 |\n| `faster server` | 服务器管理 | 启动开发服务器           |\n\n---\n\n### 🏗️ `faster app` - 应用管理命令\n\n用于快速创建项目结构和配置文件，帮助开发者快速搭建项目骨架。\n\n#### 📱 `faster app demo`\n\n创建示例应用模块\n\n```bash\nfaster app demo\n```\n\n**功能说明**：\n\n- 在项目根目录创建 `apps/` 目录（如不存在）\n- 复制内置的 `demo` 应用到 `apps/demo/`\n- 包含完整的 MVC 结构示例（models.py、routes.py、commands.py）\n\n**输出结果**：\n\n```\n✅ apps/demo created successfully\n```\n\n#### ⚙️ `faster app config`\n\n创建自定义配置目录\n\n```bash\nfaster app config\n```\n\n**功能说明**：\n\n- 复制内置配置模板到项目根目录的 `config/` 目录\n- 提供自定义配置的基础结构\n- 支持配置自动发现和合并\n\n#### 🌍 `faster app env`\n\n创建环境变量配置文件\n\n```bash\nfaster app env\n```\n\n**功能说明**：\n\n- 复制 `.env.example` 模板到项目根目录的 `.env` 文件\n- 包含所有必要的环境变量配置项\n- 如果文件已存在则跳过创建\n\n#### 🎯 `faster app main`\n\n复制框架内置的主入口文件模板\n\n```bash\nfaster app main\n```\n\n**功能说明**：\n\n- **复制内置模板**：将 Faster APP 框架内置的 `main.py` 文件复制到项目根目录\n- **支持二次开发**：用户可以基于模板进行自定义修改和扩展\n- **完整功能示例**：模板包含完整的 FastAPI 应用配置示例\n- **覆盖默认行为**：自定义后的 `main.py` 将被 `faster server start` 优先使用\n\n**使用场景**：\n\n- 🔧 需要自定义 FastAPI 应用配置\n- 🎨 想要添加自定义中间件或路由\n- ⚙️ 需要特殊的启动逻辑或初始化代码\n- 🚀 准备部署到生产环境时的配置调优\n\n**输出结果**：\n\n```\n✅ main.py created successfully\n```\n\n\u003e 💡 **提示**：复制后的 `main.py` 文件会被 `faster server start` 命令自动检测并优先使用，无需额外配置。\n\n#### 🔧 `faster app middleware`\n\n创建中间件目录\n\n```bash\nfaster app middleware\n```\n\n**功能说明**：\n\n- 复制内置中间件模板到项目根目录的 `middleware/` 目录\n- 提供中间件开发的基础结构\n- 支持中间件自动发现和注册\n\n#### 🐳 `faster app docker`\n\n创建 Docker 配置文件\n\n```bash\nfaster app docker\n```\n\n**功能说明**：\n\n- 复制优化的 `Dockerfile` 到项目根目录\n- 基于多阶段构建，适合生产环境部署\n- 包含 Python 3.11+ 和 uv 包管理器\n\n---\n\n### 🗄️ `faster db` - 数据库管理命令\n\n基于 [Aerich](https://github.com/tortoise/aerich) 实现的数据库迁移工具，提供完整的数据库生命周期管理。\n\n#### 🏗️ `faster db init`\n\n初始化数据库迁移配置\n\n```bash\nfaster db init\n```\n\n**功能说明**：\n\n- 创建 `migrations/` 目录\n- 初始化 Aerich 配置\n- 准备数据库迁移环境\n\n**输出结果**：\n\n```\n✅ Successfully created migrations folder\n```\n\n#### 🎬 `faster db init_db`\n\n初始化数据库表结构\n\n```bash\nfaster db init_db\n```\n\n**功能说明**：\n\n- 根据模型定义生成数据库表结构\n- 创建初始迁移文件\n- 适用于项目首次部署\n\n**输出结果**：\n\n```\n✅ Database initialization successful\n```\n\n#### 📝 `faster db migrate`\n\n生成数据库迁移文件\n\n```bash\n# 自动生成迁移文件\nfaster db migrate\n\n# 指定迁移文件名称\nfaster db migrate --name=\"add_user_table\"\n\n# 生成空的迁移文件\nfaster db migrate --empty\n```\n\n**参数说明**：\n\n- `--name`: 指定迁移文件名称（可选）\n- `--empty`: 生成空的迁移文件，用于手动编写迁移逻辑\n\n**输出结果**：\n\n```\n✅ Migration file generated successfully\n```\n\n#### ⬆️ `faster db upgrade`\n\n执行数据库迁移\n\n```bash\nfaster db upgrade\n```\n\n**功能说明**：\n\n- 执行所有未应用的迁移文件\n- 将数据库结构更新到最新状态\n- 支持事务回滚\n\n**输出结果**：\n\n```\n✅ Database migration execution successful\n```\n\n#### ⬇️ `faster db downgrade`\n\n回滚数据库迁移\n\n```bash\n# 回滚到上一个版本\nfaster db downgrade\n\n# 回滚到指定版本\nfaster db downgrade --version=2\n```\n\n**参数说明**：\n\n- `--version`: 指定回滚到的版本号（默认为 -1，即上一个版本）\n\n**输出结果**：\n\n```\n✅ Database downgrade successful\n```\n\n#### 📚 `faster db history`\n\n查看迁移历史\n\n```bash\nfaster db history\n```\n\n**功能说明**：\n\n- 显示所有已执行的迁移记录\n- 包含迁移文件名和执行时间\n\n#### 👀 `faster db heads`\n\n查看待应用的迁移\n\n```bash\nfaster db heads\n```\n\n**功能说明**：\n\n- 显示所有未应用的迁移文件\n- 帮助了解当前数据库状态\n\n#### 🧹 `faster db dev_clean`\n\n清理开发环境数据 ⚠️\n\n```bash\n# 交互式确认清理\nfaster db dev_clean\n\n# 强制清理（跳过确认）\nfaster db dev_clean --force\n```\n\n**参数说明**：\n\n- `--force`: 跳过确认提示，强制执行清理\n\n**功能说明**：\n\n- **仅在开发环境可用**（`DEBUG=True`）\n- 删除数据库文件和迁移目录\n- 用于重置开发环境数据\n\n**⚠️ 警告**：此操作会删除所有数据，请谨慎使用！\n\n---\n\n### 🚀 `faster server` - 服务器管理命令\n\n提供开发服务器的启动和管理功能，支持热重载和自定义配置。\n\n#### 🚀 `faster server start`\n\n启动开发服务器\n\n```bash\nfaster server start\n```\n\n**功能说明**：\n\n- **智能检测启动方式**：自动检测项目根目录下的 `main.py` 文件\n- **优先使用用户配置**：如果存在 `main.py` 则优先使用，否则使用框架内置配置\n- **热重载支持**：开发模式下自动重载代码变更\n- **完整功能集成**：自动应用日志配置、中间件、路由等\n- **灵活部署模式**：支持工厂模式和实例模式\n\n**🔍 启动检测逻辑**：\n\n1. **第一优先级**：检查项目根目录是否存在 `main.py` 文件\n\n   - ✅ **存在 `app` 实例** → 使用用户自定义的 FastAPI 应用\n   - ✅ **存在 `main()` 方法** → 执行用户自定义的启动逻辑\n   - ❌ **文件存在但无有效入口** → 提示警告，回退到框架默认配置\n\n2. **第二优先级**：使用 Faster APP 框架内置的默认配置启动\n\n\u003e 💡 **提示**：可以使用 `faster app main` 命令复制框架内置的 `main.py` 模板到项目根目录，然后根据需要进行自定义修改。\n\n**配置参数**：\n\n- **主机地址**：通过 `HOST` 环境变量配置（默认：`0.0.0.0`）\n- **端口号**：通过 `PORT` 环境变量配置（默认：`8000`）\n- **调试模式**：通过 `DEBUG` 环境变量配置（默认：`True`）\n\n**输出示例**：\n\n```\nINFO:     Started server process [12345]\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\nINFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)\n```\n\n---\n\n### 🔧 自定义命令\n\nFaster APP 支持自动发现和注册自定义命令，只需继承 `BaseCommand` 类：\n\n```python\n# apps/your_app/commands.py\nfrom faster_app.commands.base import BaseCommand\n\nclass YourAppCommand(BaseCommand):\n    \"\"\"自定义应用命令\"\"\"\n\n    def hello(self, name: str = \"World\"):\n        \"\"\"打招呼命令\"\"\"\n        print(f\"Hello, {name}!\")\n\n    def deploy(self, env: str = \"staging\"):\n        \"\"\"部署命令\"\"\"\n        print(f\"Deploying to {env} environment...\")\n```\n\n**使用方式**：\n\n```bash\n# 自动发现并注册为 your_app 命令组\nfaster your_app hello --name=\"FastAPI\"\nfaster your_app deploy --env=\"production\"\n```\n\n### 💡 使用技巧\n\n#### 1️⃣ **命令帮助**\n\n在任何命令后添加 `--help` 查看详细帮助：\n\n```bash\nfaster db migrate --help\n```\n\n#### 2️⃣ **环境变量配置**\n\n通过 `.env` 文件配置数据库连接等参数：\n\n```bash\n# 先创建配置文件\nfaster app env\n# 编辑 .env 文件后再执行数据库操作\n```\n\n#### 3️⃣ **开发工作流**\n\n推荐的项目初始化流程：\n\n```bash\n# 1. 创建基础结构\nfaster app demo          # 创建示例应用\nfaster app config        # 创建配置目录\nfaster app env           # 创建环境变量文件\n\n# 2. 自定义主入口（可选）\nfaster app main          # 复制内置 main.py 模板进行自定义\n\n# 3. 初始化数据库\nfaster db init           # 初始化迁移配置\nfaster db init_db        # 创建数据库表结构\n\n# 4. 启动开发服务器\nfaster server start      # 自动检测并使用 main.py（如存在）\n```\n\n\u003e 💡 **说明**：步骤 2 是可选的。如果不执行 `faster app main`，`faster server start` 会使用框架内置的默认配置启动。\n\n## 🤝 社区与支持\n\n### 📞 获取帮助\n\n- 📖 [完整文档](https://github.com/mautops/faster-app#readme)\n- 🐛 [问题反馈](https://github.com/mautops/faster-app/issues)\n- 💬 [讨论区](https://github.com/mautops/faster-app/discussions)\n\n### 🤝 贡献代码\n\n1. 🍴 **Fork 本仓库**\n2. 🌱 **创建特性分支**: `git checkout -b feature/amazing-feature`\n3. ✨ **提交更改**: `git commit -m 'Add amazing feature'`\n4. 🚀 **推送分支**: `git push origin feature/amazing-feature`\n5. 📝 **提交 Pull Request**\n\n### 🎨 设计原则\n\n- 📜 **约定优于配置**: 通过约定减少配置\n- 🎆 **Django 风格**: 借鉴 Django 的成功经验\n- 🚀 **开发者友好**: 提升开发效率和体验\n- 🏢 **企业级**: 满足生产环境需求\n\n---\n\n## 📄 许可证\n\n本项目采用 [MIT 许可证](LICENSE)。\n\n## 🙏 致谢\n\n感谢以下开源项目的启发：\n\n- ⚡ [FastAPI](https://fastapi.tiangolo.com/) - 现代、快速的 Web 框架\n- 🐢 [Tortoise ORM](https://tortoise.github.io/) - 异步 ORM 框架\n- 🔥 [Fire](https://github.com/google/python-fire) - 命令行接口生成器\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ 如果这个项目对你有帮助，请给我们一个 Star！**\n\n**作者**: [peizhenfei](mailto:peizhenfei@hotmail.com) | **项目主页**: [GitHub](https://github.com/mautops/faster-app)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmautops%2Ffaster-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmautops%2Ffaster-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmautops%2Ffaster-app/lists"}