{"id":20839314,"url":"https://github.com/dovolopor-research/python-api-template","last_synced_at":"2025-09-01T20:41:25.127Z","repository":{"id":102506997,"uuid":"534870917","full_name":"dovolopor-research/python-api-template","owner":"dovolopor-research","description":"🐍 一个快速高性能的「Python API 模板」","archived":false,"fork":false,"pushed_at":"2024-01-08T15:26:45.000Z","size":13,"stargazers_count":15,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T18:20:18.011Z","etag":null,"topics":["python-api","python-template","sanic","sanic-project"],"latest_commit_sha":null,"homepage":"","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/dovolopor-research.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}},"created_at":"2022-09-10T02:42:00.000Z","updated_at":"2025-06-04T01:11:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"2efb00e8-cdd1-4ca7-8ad9-183b8d783756","html_url":"https://github.com/dovolopor-research/python-api-template","commit_stats":null,"previous_names":["dovolopor-research/python-api-template","ailln/python-api-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/dovolopor-research/python-api-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovolopor-research%2Fpython-api-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovolopor-research%2Fpython-api-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovolopor-research%2Fpython-api-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovolopor-research%2Fpython-api-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dovolopor-research","download_url":"https://codeload.github.com/dovolopor-research/python-api-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovolopor-research%2Fpython-api-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263893573,"owners_count":23526313,"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":["python-api","python-template","sanic","sanic-project"],"created_at":"2024-11-18T01:13:16.534Z","updated_at":"2025-07-06T11:33:14.821Z","avatar_url":"https://github.com/dovolopor-research.png","language":"Python","readme":"# Python API Template\n\n🐍 一个**快速高性能**的「Python API 模板」\n\n## 0 快速启动\n\n```shell\npip install -r requirements.txt\n\npython -m server.main\n```\n\n## 1 目录简介\n\n```\n.\n├── README.md             # 简介\n├── server                # 部署\n│   └── app.py\n├── conf                  # 配置\n│   ├── default.prod.yaml # 生产配置\n│   ├── default.test.yaml # 测试配置\n│   └── default.yaml      # 开发配置\n├── util                  # 辅助\n│   ├── conf.py\n│   ├── log.py\n│   └── data_model.py     # 类型定义\n├── script                # 脚本\n│   ├── sync.sh           # 同步到服务器\n│   ├── build.sh          # 打包镜像\n│   └── run.sh            # 运行容器\n├── test                  # 测试（可选）\n│   └── api_test.py\n├── doc                   # 文档（可选）\n├── log                   # 日志\n├── Dockerfile            # Docker 打包配置（可选）\n├── .dockerignore         # Docker 忽略配置（可选）\n├── .gitignore            # Git 忽略配置\n├── requirements.txt      # 依赖（可选）\n└── LICENSE               # 许可\n```\n\n### 1.1 README.md（文档）\n\n**一个详尽的文档比什么都重要！** 任何人都可以通过文档快速上手。也许你会说，我的代码就我自己看，不写文档也知道。可是你能保证三个月以后，你还记得你当初写的什么吗？！\n\n一个好的项目文档应该是怎样的？\n\n1. 环境依赖说明\n2. 快速运行脚本\n3. 类似项目比较\n4. 性能测试结果\n5. 细致版本记录\n6. 相关参考资料\n\n参考：\n\n1. [如何写好Github中的readme？](https://www.zhihu.com/question/29100816)\n2. [如何为你的开源项目编写实用的文档](https://zhuanlan.zhihu.com/p/120399648)\n\n### 1.2 util（辅助工具）\n\n一些常见的辅助函数，比如：\n\n1. conf 配置\n2. data_model 类型注解\n3. log 日志\n\n### 1.3 conf（配置中心）\n\n所有的配置都是用 `YAML`，它比 `json` 更好用，可以在配置中添加注释，并且呈现方式也更为直观！\n\n配置文件的中间名称是「环境变量」，比如 ENV 为 `test` 时，就会读取 `default.test.yaml` 文件（ENV 默认为 `dev`，会读取 `default.yaml`）。\n\n如何使用环境变量 ENV 呢？只需要在执行时，把 `ENV=test` 添加到命令的最前面，比如 `ENV=test python -m server.main`。\n\n```shell\n# 默认是 ENV 是 dev\npython -m server.main\n# or\nENV=dev python -m server.main\n```\n\n### 1.4 server（部署）\n\n使用 Web 服务部署到线上环境，推荐使用 [FastAPI](https://fastapi.tiangolo.com/zh/)。\n\n1. **高性能**：FastAPI 是基于 Starlette 和 Pydantic 构建的，因此它具有非常高的性能。与其他 Python Web 框架相比，它的速度更快，甚至可以与 Node.js 和 Go 这样的高性能语言竞争。\n2. **易用性和开发效率**：FastAPI 使用了现代 Python 特性，如类型提示，使得代码易于阅读和编写。这有助于提高开发者的生产力以及减少错误。另外，它自动生成 API 文档（使用 OpenAPI 和 JSON Schema），方便开发者查看和测试 API 接口。\n3. **丰富地插件和社区支持**：FastAPI 提供了许多内置组件，如身份验证、安全、数据验证等，可帮助您快速构建 Web 应用。同时，由于 FastAPI 的普及，其拥有一个庞大的活跃社区，为开发者提供大量第三方库和技术支持。\n\n\u003e 在过去本项目推荐使用 [Sanic](https://sanic.dev/zh/)，你可以在这个分支 [branch/sanic](https://github.com/Ailln/python-api-template/tree/sanic) 找到过去的代码。\n\n```shell\n# 开发环境运行\npython -m server.main\n\n# 测试环境运行\nENV=test python -m server.main\n\n# 生产环境运行\nENV=prod python -m server.main\n```\n\n### 1.5 test（测试）\n\n`api_test.py` 是对 API 接口进行压力测试，得到 QPS（每秒请求数）。\n\n`Locust` 是一个非常好用的测试工具，它附带一个 WEB 界面，非常方便地在浏览器中进行压测。\n\n```shell\nlocust -f test/api_test.py -u 10 -r 1\n```\n\n在浏览器中打开 `http://127.0.0.1:8089`，点击 `Start swarming` 按钮，就可以开始压测了！\n\n参考：\n1. [Python unittest: 单元测试框架](https://docs.python.org/zh-cn/3/library/unittest.html)\n2. [Locust: An open source load testing tool.](https://locust.io)\n\n### 1.6 doc（文档｜可选）\n\n如果项目比较复杂，可以将文档整理归纳到这里。\n\n### 1.7 log（日志）\n\n`util/log.py` 会将日志按天记录到 log 目录下。\n\n### 1.8 requirements.txt （依赖）\n\n项目所需要的依赖，方便一键安装。\n\n```shell\n# 直接安装\npip install -r requirements.txt -i https://pypi.mirrors.ustc.edu.cn/simple\n```\n\n参考：\n\n1. [有关 pip 的使用](https://www.v2ai.cn/2019/12/20/python/7-pip/)\n\n### 1.9 LICENSE（许可｜可选）\n\n如果是开源项目，需要添加许可证。\n\n参考：\n\n1. [一文看懂开源许可证丨开源知识科普](https://pingcap.com/zh/blog/introduction-of-open-source-license)\n2. [如何选择开源许可证？](https://www.ruanyifeng.com/blog/2011/05/how_to_choose_free_software_licenses.html)\n\n## 2 环境准备\n\n- Ubuntu 18.04 LTS+\n- Python 3.8+\n- Docker 21+\n\n\u003e 人生苦短，快用 `*NIX` ！\n\n## 3 容器化部署\n\n```shell\ncd python-api-template\n\n# 直接打包\ndocker build -t python-api-template:1.0.0 .\n# or 使用脚本打包\nbash script/build.sh\n\n# 直接运行\ndocker run -d  --restart=always \\\n  --name python-api \\\n  -p 9999:9999 \\\n  -v $PWD/conf/:/app/conf \\\n  -e ENV=prod \\\n  python-api-template:1.0.0\n# or 使用脚本运行\nbash script/run.sh\n\n# 查看\ndocker logs -f python-api-template\n\n# 调用 API\ncurl --location --request POST 'http://127.0.0.1:9999/test' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"data\": \"test\"\n}'\n```\n\n## 4 参考\n\n- [Ubuntu 系统镜像下载](https://cn.ubuntu.com/download)\n- [Anaconda 个人版](https://www.anaconda.com/products/individual#)\n- [TUNA 清华大学开源软件镜像站](https://mirrors.tuna.tsinghua.edu.cn/)\n\n## 5 许可证\n\n[![](https://award.dovolopor.com?lt=License\u0026rt=MIT\u0026rbc=green)](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovolopor-research%2Fpython-api-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdovolopor-research%2Fpython-api-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovolopor-research%2Fpython-api-template/lists"}