{"id":19298631,"url":"https://github.com/ibbd-dev/fastapi-start","last_synced_at":"2025-04-22T09:32:37.650Z","repository":{"id":38192196,"uuid":"374857107","full_name":"ibbd-dev/fastapi-start","owner":"ibbd-dev","description":"FastAPI脚手架：用于系统后端接口项目的","archived":false,"fork":false,"pushed_at":"2023-10-18T10:16:08.000Z","size":519,"stargazers_count":77,"open_issues_count":4,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T22:03:35.986Z","etag":null,"topics":["fastapi","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibbd-dev.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}},"created_at":"2021-06-08T02:28:35.000Z","updated_at":"2025-03-23T15:01:48.000Z","dependencies_parsed_at":"2022-09-13T09:00:21.865Z","dependency_job_id":"be7d3c4b-91fe-45cb-ae46-f559ce0a18e0","html_url":"https://github.com/ibbd-dev/fastapi-start","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbd-dev%2Ffastapi-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbd-dev%2Ffastapi-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbd-dev%2Ffastapi-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbd-dev%2Ffastapi-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibbd-dev","download_url":"https://codeload.github.com/ibbd-dev/fastapi-start/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250215328,"owners_count":21393782,"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","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":["fastapi","python"],"created_at":"2024-11-09T23:08:34.941Z","updated_at":"2025-04-22T09:32:37.303Z","avatar_url":"https://github.com/ibbd-dev.png","language":"Python","readme":"# FastAPI脚手架：用于系统后端接口项目\n\n该工具主要用于协助规范FastAPI项目的目录及代码风格等。工具目标：\n\n- 规范FastAPI后端接口项目开发。\n- 提升后端​开发效率，减少重复工作。\n- 增加不同项目间共享模块开发的可能性​。\n\n## 1. 功能介绍\n\n- [x] 项目初始化（生成规范的项目目录）\n- [x] 添加模块（添加内置模块或者全新模块）\n- [x] 生成Python文件（自动加上规范的文件头信息）\n- [x] 替代git clone命令的clone命令，并生成标准化的目录路径\n- [x] 统一接口异常响应信息结构\n- [x] 快速从已有数据库中生成模型文件\n- [ ] S3支持，统一去除文件的本地系统依赖\n- [x] 规范日志模块\n- [x] http请求的统一封装\n- 代码审查工具:\n  - [x] 代码风格检测与自动修复（保证代码满足PEP8规范）\n  - [x] 代码静态类型检测（自动检测变量的类型，减少低级错误）\n  - [ ] 测试覆盖率工具\n\n### 1.1 内置模块列表\n\n- [x] 验证码\n- [ ] 用户管理\n- [ ] celery\n- [ ] 数据库迁移\n\n## 2. 安装说明\n\n```sh\n# 推荐安装方式\n# linux\nsudo -H pip3 install -r https://github.com/ibbd-dev/fastapi-start/raw/main/requirements.txt\nsudo -H pip3 install git+https://github.com/ibbd-dev/fastapi-start.git\n\n# windows\npip install -r https://github.com/ibbd-dev/fastapi-start/raw/main/requirements.txt\npip install git+https://github.com/ibbd-dev/fastapi-start.git\n```\n\nOR\n\n```sh\n# 源码安装\ngit clone https://github.com/ibbd-dev/fastapi-start\ncd fastapi-start\npip install -r requiresment.txt\n\n# install\npip install .\n\n# 测试\nfas\n```\n\n说明：执行fas命令时如果报错：\n\n```text\nTraceback (most recent call last):\n  File \"D:\\Apps\\Anaconda3\\Scripts\\fas-script.py\", line 33, in \u003cmodule\u003e\n    sys.exit(load_entry_point('fastapi-start==0.6.7', 'console_scripts', 'fas')())\n  File \"D:\\Apps\\Anaconda3\\Scripts\\fas-script.py\", line 25, in importlib_load_entry_point\n    return next(matches).load()\nStopIteration\n```\n\n解决：\n\n```sh\ncd /mnt/d/Apps/Anaconda3/Lib/site-packages\nrm -rf fastapi_start*\n```\n\n说明：以上都只在windows和ubuntu上测试通过，还没在mac上有测试过。\n\n## 3. 使用说明\n\n安装成功之后，会有两个命令\n\n- `fastapi-start`: 完整命令\n- `fas`: 简单命令（完整命令的别名），实现功能和完整命令一样\n\n日常使用简单命令即可。\n\n### 3.1 快速上手\n\n```sh\n# 创建项目目录\nmkdir project_name\ncd project_name\n\n# 初始化项目\nfas project init --title=测试项目  --desc=这是一个测试项目\n```\n\n### 3.2 项目日常使用\n\n```sh\n# 创建一个test新项目并初始化\n# test是项目名称，可以指定为自己的项目名称\n# --title and --desc: 项目的标题及描述\nfas project create test --title=测试项目 --desc=这是一个测试项目\ncd test\n\n# 或者如果项目目录已经存在，如项目目录test已经存在，则先去到该目录\ncd test\nfas project init --title=测试项目 --desc=这是一个测试项目\n\n# 实际开发强烈建议使用虚拟环境\n# 使用帮助：\nvirtualenv --help\n\n# 项目代码目录\ncd app\n\n# 启动http服务\nuvicorn main:app --reload --host 0.0.0.0\n# 在浏览器打开：http://127.0.0.1:8000/docs#/\n# 查看接口文档\n\n# 添加一个模块\n# test是模块名称，可以设定\nfas module new --name=test\n\n# 添加模块之后，要使模块生效，需要手动在app/main.py文件中注册该路由\n# prefix: 该参数定义路由的前缀，每个模块的路由前缀必须是唯一的\nfrom test_module.router import router as test_router\napp.include_router(test_router, prefix=\"/test\", tags=[\"测试模块\"])\n\n# 在当前目录增加一个test.py文件\n# python是文件类型，test是文件名\nfas file python test\n```\n\n### 3.3 帮助文档\n\n```sh\n# 显示所有帮助文档\nfas --help\n\n# 某个命令的帮助文档\nfas project --help\nfas project init --help\nfas project create --help\n\n# 查看版本号\nfas version\n\n# 设置git clone命令的根目录\nfas config set --root-path=/var/www/src\n\n# 可以查看配置信息\nfas config get\n\n# clone项目\n# 项目会自动保存到规范化的目录中：{root-path}/git.ibbd.net/gf/iot-test\n# root-path就是前面设置的配置： fas config set --root-path=/var/www/src\nfas clone git@git.ibbd.net:gf/iot-test.git\n\n# 在当前目录生成README.md\nfas file readme --title=测试标题 --desc=描述信息\n```\n\n### 3.4 代码审查\n\n```sh\n# 帮助文档\nfas check --help\n\n# 审查当前目录\nfas check flake8 --help\nfas check flake8\n\n# 审查指定目录（假设app是项目代码所在目录）\nfas check flake8 app\n\n# 对于某种类型的问题，可以启用自动修正，如：\nfas check flake8 --path app --select=W292 --autopep8\n# 不过使用自动修正时要注意检查比较\n\n# 代码静态风格检测\nfas check mypy --help\nfas check mypy /path/to/filename.py\n```\n\n使用说明：\n\n- 风格审查使用的工具是`flake8`，直接使用也一样。\n- 并不是所有不规范的地方都应该修复，例如行代码过长的问题，如果不是很离谱，则可以不处理（当然，最好还是处理）。\n\n## 4. FastAPI项目开发\n\n编码风格遵循[PEP8](https://alvinzhu.xyz/2017/10/07/python-pep-8/)，接口风格参考[RESTFul](https://mp.weixin.qq.com/s/EOzkOlhrT4pvWIyJ_kfcqw)。\n\n重要规则说明：\n\n- 开发测试强烈建议使用虚拟环境进行（或者直接使用docker），部署则使用docker\n- 使用4个空格缩进，换行符使用`\\n`（vscode编辑器需要配置为LF，而不是CRLF）\n- 文件统一使用UTF-8编码\n- 接口响应的异常类型使用HTTP的状态码\n- HTTP方法的使用场景：\n  - GET: 获取数据\n  - DELETE: 删除数据\n  - PUT: 修改数据\n  - POST: 增加数据和复杂查询\n- 函数的输入输出的参数类型需要明确的类型定义，粒度到最基础的简单类型，如布尔值，整型，浮点型，字符串等。对于复杂类型，则应该进一步细化：\n\n```python\nfrom typing import Tuple, List, Dict, Set\n\n# 元组\nTuple[int, str, int]  # 三个元素的元组\n\n# 列表\nList[int]    # 元素类型为int的列表\n\n# 字典\nDict[str, int]    # key类型为str，value类型为int\n\n# 集合（和列表类型）\nSet[int]\n```\n\n参考[Python类型编程](https://mp.weixin.qq.com/s/N_AfjCWg_gcQzqs22KEgVA)\n\n- 在FastAPI中则尽量不要定义字典的输入输出，而是使用继承于`BaseModel`的类结构，可以详细定义每个字段的schema。\n\n### 4.1 基于FastAPI的大中型项目应该具备\n\n- 函数的参数和返回值必须要有明确的参数类型定义。\n- 模块应该使用路由进行组织，模块内紧外松。\n- 接口必须要有单元测试，部署时可以执行单元测试来验证。\n- 交互式文档应该清晰明了，使用者能方便阅读，理解与测试。\n\n### 4.2 项目目录结构\n\n```sh\n.\n├── venv                         # python虚拟环境目录\n├── app                          # 项目主目录\n│   ├── __init__.py\n│   ├── readme.md                # 接口的描述文档\n│   ├── init_app.py              # app初始化\n│   ├── main.py                  # 主入口文件\n│   ├── schema.py                # 通用schema\n│   ├── settings.py              # 配置文件\n│   ├── dependencies.py          #\n│   ├── exceptions.py            # 异常相关\n│   ├── utile.py                 # 通用的工具函数\n│   ├── common                   # 公共模块\n│   |   ├── __init__.py\n│   │   └── connections.py       # redis, mysql等连接公共函数\n│   └── module_name              # 模块目录，每个模块独立成一个目录\n│       ├── __init__.py\n│       ├── README.md            # 模块说明文件\n│       ├── router.py            # 模块路由文件\n│       ├── schema.py            # 模块的schema\n│       └── requirements.txt     # 模块依赖项\n├── .vscode                      # vscode配置\n│   └── settings.json\n├── .gitignore\n├── README.md                    # 项目说明文档\n├── Dockerfile                   # Docker\n└── requirements.txt             # 项目依赖包\n```\n\n模块的路由及其配置文件直接放到模块目录下，而不是将所有路由配置独立到一个目录。\n\n### 4.3 内置模块\n\n内置模块，可以使用命令进行快捷添加。\n\n```sh\n# module命令帮助文档\nfas module --help\n\n# 查看module命令的子命令的帮助文档\nfas module add --help\n\n# 支持的模块列表\nfas module list\n\n# 查看某内置模块的帮助文档\nfas module help captcha\n\n# 添加内置模块\nfas module add captcha\n```\n\n#### 4.3.1 验证码模块\n\n[使用文档](/app/project/captcha_module/README.md)\n\n### 4.4 注意事项\n\n- 模块下还可以嵌套子模块，不断套娃，但是不建议这么干，这会让系统变得过于复杂；\n\n## 5. Python编码规范\n\n- [PEP8规范](https://alvinzhu.xyz/2017/10/07/python-pep-8/)\n- [Google的开源项目风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/)\n- [RESTFul](https://mp.weixin.qq.com/s/EOzkOlhrT4pvWIyJ_kfcqw)\n- [Python类型编程](https://mp.weixin.qq.com/s/N_AfjCWg_gcQzqs22KEgVA)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibbd-dev%2Ffastapi-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibbd-dev%2Ffastapi-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibbd-dev%2Ffastapi-start/lists"}