Skip to content

python fastapi web framework boilerplate, python3.7 + fastapi + uvicorn + gunicorn

License

Notifications You must be signed in to change notification settings

smileboywtu/fastapi-boilerplate

Repository files navigation

Fastapi WEB 开发模版

Fastapi 使用了 Python 的异步 IO 特性,可以提升比较多的性能,API 使用起来比较简洁直观,更加符合开发者的习惯。

Fastapi 更多特性参考文档

本模版在 Fastapi 的功能基础上集成了更多常用的功能,用户可以根据自己的需求进行删减,删减比增加可能更加容易一些。

为什么要开发这个项目

其实这个项目几年前都开放了,但是后来一直没怎么维护,最近整理资料时一并升级了相关的代码,维护这个项目的出发点:

  • 不重复走弯路。自己重新整理的过程中好多依赖和能力都发生了更新,整理还是比较费时的,特别是老旧代码兼容的问题,整理成快速开发的模版,方便下次快速应用,不重复走弯路。
  • 让好用的东西更简单的被使用。自己开发 web 也有很多年了,也见过比较多优秀业务系统,他们承载着高并发和丰富的系统功能,这些能力都与底层的技术结构分不开,新手刚入行的时候,对这些东西的了解是比较少的,要学习的东西很多,所以如果刚开始有一个比较完善的开发模版,有助于能力提升,少走弯路,尽量把精力留给其他需要探索的事情。

模版结构

整个模版一共有 4 个功能模块, 7 个组件:

特性支持

  • 较好的移植性:使用 Docker/DockerCompose 开发部署。
  • 高性能 Python IO:使用 AsyncIO/Fastapi 开发,开发简单,性能高。
  • 分布式 Log 支持:自定义 TCP Log Server 分布式收集 WEB 日志,提供 JSON 格式,可供分析统计。
  • ORM/plain SQL:支持使用 ORM 或者直接使用 SQL 也可,其中 ORM 使用 SQL Alchemy,普通的 SQL 使用 aiosql 维护调度。
  • 易于开发调试:提供开发环境调试助手,可以针对各个子模块单独调试,子功能进行调试。
  • API 自动化测试支持:可以使用 pytest 进行 API 自动测试。

性能测试

备注:历史数据,未更新

使用 WRK 进行测试,可通过运行 benchmark.sh 来测试。

测试硬件信息

aliyun ECS 16C 32G 2.4G with 8 process.

不使用数据库参与压测

测试使用 4 线程 300 并发进行测试,测试 echo 模式:

./wrk -t 4 -c 400 -d10s http://127.0.0.1:8000/api/v1/user/greeting
Running 10s test @ http://127.0.0.1:8000/api/v1/user/greeting
  4 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    33.45ms   77.33ms   1.01s    96.80%
    Req/Sec     5.35k     2.66k   12.48k    66.75%
  212805 requests in 10.05s, 43.43MB read
  Socket errors: connect 0, read 2078, write 0, timeout 0
Requests/sec:  21179.64
Transfer/sec:      4.32MB

Postgres 参与测试

测试使用 4 线程 300 并发进行测试,测试时 postgres 参与读取:

./wrk -t 4 -c 300 -d10s http://127.0.0.1:8000/api/v1/user/list
Running 10s test @ http://127.0.0.1:8000/api/v1/user/list
  4 threads and 300 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    66.94ms   49.40ms 604.50ms   73.71%
    Req/Sec     1.22k   252.57     1.87k    64.75%
  48659 requests in 10.10s, 11.09MB read
Requests/sec:   4819.52
Transfer/sec:      1.10MB

Redis 参与测试

测试使用 4 线程 300 并发进行测试,测试时 redis 参与读取:

./wrk -t 4 -c 400 -d10s http://127.0.0.1:8000/api/v1/user/counter
Running 10s test @ http://127.0.0.1:8000/api/v1/user/counter
  4 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    58.08ms  140.53ms   1.05s    94.98%
    Req/Sec     4.04k     1.95k    8.53k    66.00%
  160779 requests in 10.04s, 31.89MB read
  Socket errors: connect 0, read 1820, write 0, timeout 0
Requests/sec:  16012.11
Transfer/sec:      3.18MB

运行

环境变量配置

系统运行之前,需要配置一下环境变量,环境变量存储在 .env/.production 文件夹中,环境变量中尽量不要添加注释,否则无法解析。

cp .sample.fastapi .env/.production/.fastapi
cp .sample.postgres .env/.production/.postgres

拷贝进去之后根据自己的需要修改相应的配置,主要需要关注:

  • POSTGRES_DATA_DIR:用来存储 postgres 文件,防止数据库内容丢失,不要存储在 docker 容器中。
  • LOG_BASE_PATH:fastapi web access 日志存储目录,会自动备份删除日志,方便后续日志分析和查询。
  • CELERY_BEAT_DBFILE_DIR:celery 定时任务运行记录,存储定时任务的运行情况。

配置完成,请检查环境变量是否配置符合预期,检查办法:

# 测试不同的变量获取是否符合预期
eval $(cat .envs/.production/.fastapi .envs/.production/.postgres) echo "${POSTGERS_PORT}"

其余变量根据自己的情况配置,非必要配置。

环境准备

如果使用 docker-machine 测试开发项目时,则可以直接运行即可,跳过此节。如果是在 linux 环境中开发测试,需要处理好文件权限的问题,目前 celery / fastapi 日志均需要使用系统文件夹存储,所以需要给文件夹添加权限。

目前项目使用的用户组和用户信息:

  • UID:1000
  • GID:1000

在运行之前,需要针对宿主文件夹:

  • CELERY_BEAT_DBFILE_DIR
  • LOG_BASE_PATH 进行授权,授权方法为:
chown -R 1000:1000 your_CELERY_BEAT_DBFILE_DIR
chmod g+s your_CELERY_BEAT_DBFILE_DIR
chown -R 1000:1000 your_LOG_BASE_PATH
chmod g+s your_LOG_BASE_PATH

测试运行

使用了 make 简化管理,也可以自己使用 docker-compose 命令,但是使用单独的命令时,环境变量需要做适当的调整,不允许在环境变量配置文件中使用系统环境变量。

# build docker image
make build

# start all application
make up

# stop all application
make down

本地开发

本地开发时,可以使用 docker-compose 命令将本地的 postgres/redis 等数据库启动起来,剩下的 web 服务或者定时任务可以通过开发命令的方式来启动调试,具体的方法是:

conda create -n fastapi
pip install -r requirements.txt
python dev_manage_cmd.py --help

可根据自己的需求启动相应的命令即可,也可以通过此助手调试 web 应用,启动调试助手会自动优先加载环境变量文件,请配置好环境变量之后再启动,否则可能出现意外的报错。

注意:默认的 compose 配置中每个应用仅有单独的一个实例,未配置多实例部署,生产环境中,建议配合 docker swarm/ replica 实现多机器多实例部署。

扩展

后续在单独的使用文档中说明。

联系方式

本项目不接受指导或者文档以外的支持,如有定制需求,咨询 smileboywtu@gmail.com