项目介绍

性能测试

启动服务

docker run --rm -ti \  --cpus 1 \  --net host \  -e flyer_port=8080 \  -e flyer_access_log=0 \  jagerzhang/fastflyer:latest

启动压测

[root@VM-10-150-centos opt]# ./wrk -c 100 -t 10 http://127.0.0.1:8080/health_check/asyncRunning 10stest @ http://127.0.0.1:8080/health_check/async  10 threads and 100 connections  Thread Stats   Avg      Stdev     Max   +/- Stdev    Latency    10.52ms  407.38us  14.39ms   93.83%    Req/Sec     0.95k    37.60     1.01k    58.20%  95780 requestsin 10.08s, 13.98MBreadRequests/sec:   9499.92Transfer/sec:      1.39MB

压测结果

快速体验

docker run --rm -ti \  --cpus 1 \  --net host \  -e flyer_port=8080 \  -e flyer_access_log=1 \  jagerzhang/fastflyer:latest

正式开发

项目结构说明

.├── app# 应用目录，FastFlyer 将自动加载本目录下符合框架规范的应用。│   ├── __init__.py# 导入文件，将目录加入 PYTHOHPATH，用于缩短应用内部包导入，from items.module import xxxx│   ├── items# 演示项目1：项目管理，主要演示单个路由文件如何导入│   │   ├── __init__.py# 应用入口，这里必须导入路由对象：from .router import router ，注意最终对象必须为 router，框架仅支持加载名为 router 的路由实例对象│   │   ├── module.py# 逻辑模块文件│   │   ├── README.md# 应用自述文件│   │   ├── router.py# 应用路由定义│   │   └── schema.py# 应用输入输出参数定义│   ├── tasks# 演示项目2：演示后台线程、定时任务的调度管理│   │   ├── __init__.py# 任务加载入口│       ├── README.md# 应用自述文件│   │   └── module.py# 后台任务代码│   └── users# 演示项目3：用户管理，主要演示多个路由文件如何聚合给框架加载│       ├── __init__.py# 应用入口，这里必须导入路由对象：from .routers import router ，注意最终对象必须为 router，框架仅支持加载名为 router 的路由实例对象│       ├── modules# 逻辑模块目录│       │   ├── __init__.py# 包入口文件，必须存在│       │   ├── relationship.py# 用户关系逻辑代码│       │   └── userinfo.py# 用户信息逻辑代码│       ├── README.md# 应用自述文件│       ├── routers# 应用路由目录│       │   ├── __init__.py# 应用入口，这里有别于演示应用1，这里有多路由文件的聚合逻辑，如果是多路由方式请仔细查看这个文件的实现方式│       │   ├── relationship.py# 用户关系路由定义│       │   └── userinfo.py# 用户信息路由定义│       └── schemas# 应用输入输出参数定义文件夹│           ├── __init__.py# 包入口文件，必须存在│           ├── relationship.py# 用户关系相关接口参数定义│           └── userinfo.py# 用户信息相关接口参数定义├── docker# 存放容器启动配置脚本等│   ├── docker-entrypoint.sh# 容器启动前置脚本│   └── health_check.sh# 健康检查脚本（针对于北极星方式）├── Dockerfile# Docker 镜像构建脚本├── __init__.py# SDK默认生成的空文件，可以删除├── main.py# 项目入口文件，正常无需改动├── README.md# 框架自动生成的文档，可以根据实际情况修改├── requirements.txt# 除SDK之外的业务项目依赖包，默认为空，可根据情况添加，建议带上版本号├── settings.py# 项目基础配置，继承SDK框架基础配置，可以覆盖SDK配置├── start-reload.sh# 开发环境启动脚本，基于uvicorn，支持热加载特性├── start.sh# 生产环境启动脚本，基于gunicorn├── ctrl.sh# 开发环境辅助脚本，仅支持Docker环境

创建项目

【可选】安装框架SDK

# 安装或更新 fastflyerpip3 install --upgrade fastflyer

创建全新项目

# 定义项目名变量，方便后面命令行引用export new_project=myproject# 创建项目目录并进入。默认在 /data下，可以自行修改mkdir -p /data/${new_project}cd /data/${new_project}# 生成初始项目代码docker run --rm -v `pwd`:/fastflyer -ti jagerzhang/fastflyer:latest fastflyer create openapi --name=${new_project} --prefix=/${new_project}# 上传代码到既定代码库（请自行修改仓库地址）git init --initial-branch=mastergit remote add origin https://github.com/yourname/${new_project}.gitgit add .git commit -m "Initial commit"git push --set-upstream origin master

基于Docker搭建开发环境

参数说明

欢迎使用 FastFlyer 开发环境辅助工具。用法: ./dev_ctrl.sh <OPTION>命令:     start        启动开发容器     show [D]     查看开发容器     login        进入开发容器     update       更新容器插件     restart      重启开发容器     reset        重建开发容器     destroy      销毁开发容器     log [COUNT]  查看容器日志

运行服务

# 进入项目代码根目录cd /data/my_project/<new_project># 一键拉起开发容器./dev_ctrl.sh start

基于Linux搭建开发环境（不推荐）

cd /data/my_project/<new_project>./start-reload.sh

内建功能

获取变量

方式一、框架内置对象方式获取

fromfastflyerimportenv# 框架提供的变量获取有以下 4 种方式，业务可以自行根据喜好选择：# 类 os.getenv 方式custom_env_name=env.get("custom_env_name","default_value")# 对象获取变量方式1：表达式配置默认值custom_env_name=env.custom_env_nameor"default_value"# 对象获取变量方式2：item 方式配置默认值custom_env_name=env.custom_env_name["default_value"]# 对象获取变量方式3：传参方式配置默认值custom_env_name=env.custom_env_name("default_value")print(f"custom_env_name：{custom_env_name}")

方式二、原生内置插件方式获取

fromosimportgetenvcustom_env_name=getenv("custom_env_name","default_value")print(f"custom_env_name：{custom_env_name}")

日志打印

fromfastflyerimportlogger# 打印文本logger.debug("DEBUG级别")logger.info("INFO级别")logger.warn("WARN级别")logger.error("ERROR级别")# 启用日志汇之后，可以传入字典消息，如果需要再日志汇做结构化解析，则需要先json.dumpsimportjsonlogger.info(json.dumps({"field":"123"}))

本地缓存

importtimefromfastkit.cacheimportget_cacheout_pool# 类 redis 用法举例：缓存键值对120秒cache=get_cacheout_pool(cache_name="custom")cache.set("a",1,120)a=cache.get("a")# 装饰器用法举例：函数返回结果缓存120s# 若不设置 cache_key, 将自动生成，生成逻辑为：# key = f"{func.__module__}.{func.__name__}:{args}:{kwargs}"# f"{func.__module__}.{func.__name__}:{get_md5(key)}"@cache.cache_result(cache_key="foo_result",ttl=120)deffoo():# 缓存后，再次执行函数将直接返回bar，不会感知 time.sleep 阻塞耗时time.sleep(5)return"bar"

HTTP请求

fromfastflyerimportloggerfromfastflyerimportClient# 发起 GET 请求示例url="https://httpbin.org/get"headers= {"User-Agent":"My User Agent"}params= {"param1":"value1","param2":"value2"}requests=Client()response=requests.get(url,headers=headers,params=params)print(response.status_code)print(response.text)# 发起 POST 请求示例url="https://httpbin.org/post"payload= {"key":"value"}response=requests.post(url,json=payload)print(response.status_code)print(response.text)

fromfastflyerimportloggerfromfastflyerimportAsyncClient# 变量定义略asyncdeftest():aiorequests=AsyncClient()resp=awaitaiorequests.get(url=url,headers=headers)ifresp.status_code!=200:logger.error("请求失败")# 其他内容略

fromfastflyerimportClientREQUEST_RETRY_CONFIG= {"stop_max_attempt_number":3,# 最大重试 3 次"stop_max_delay":60,# 最大重试耗时 60 s"wait_exponential_multiplier":2,# 重试间隔时间倍数 2s、4s、8s..."wait_exponential_max":10# 最大重试间隔时间 10s}requests=Client(**REQUEST_RETRY_CONFIG)

fromfastflyerimportClientrequests=Client(timeout=60,headers={"content-type":"application/json"})

任务调度

定时调度同步方法

fromfastflyerimportbackground_schedulerdefcustomfunc():print("hello world!")# single_job 为 True 的时候将执行单实例单进程任务（需要设置redis配置，方能多实例/进程互斥）background_scheduler.add_job(func=customfunc,"interval",seconds=5,single_job=True)

定时调度异步方法

fromfastflyerimportasyncio_schedulerasyncdefcustomfunc():print("hello world!")# single_job 为 True 的时候将执行单实例单进程任务（需要设置redis配置，方能多实例/进程互斥）asyncio_scheduler.add_job(func=customfunc,"interval",seconds=5,id="customjob")

启动后台线程任务

"""示例任务"""fromfastflyerimportlogger,threadpool# 方式1：采用装饰器方式添加任务@threadpool.submit(single_job=True)# single_job 为 True 的时候全局只会有一个任务执行，其他的将等待锁释放defhello_world_thread():# 直到线程池停止才结束循环whilenotthreadpool.is_stopped():logger.warning(f"hello world by threadpool every 5 senconds!")# 内置可被中断的sleep，推荐使用threadpool.sleep(5)# 方式2：显式提交任务方式threadpool.submit_task(hello_world_thread,single_job=True)

Opentelemetry

公共组件

Redis

# settings.pyfromfastflyer.cacheimportget_redis_poolclassCache:# 初始化Redisredis_host=getenv("flyer_redis_host","localhost")redis_port=getenv("flyer_redis_port",6379)redis_pass=getenv("flyer_redis_pass","")redis_db=getenv("flyer_redis_db",1)redis_pool=get_redis_pool(redis_host,redis_port,redis_pass,redis_db)# 业务代码from<app_dir>.settingsimportCacheCache.redis_pool.set("a",1)Cache.redis_pool.get("a")

MySQL

SQLAlchemy

fromfastkit.databaseimportMySQL# 初始化mysql连接对象mysql_pool=MySQL(db_host,db_port,db_database,db_user,db_pass,db_charset)# 获取session连接对象session=mysql_pool.get_session()# 获取table对象table=mysql_pool.get_table(table_name)# 可以进行相关的ORM操作，示例如下data=session.query(table.c.id,table.c.name).filter(table.c.city=="shenzhen").all()# 回收session会话session.close()# 关闭所有的链接，关闭连接池mysql_pool.close(session)

DataSet

# 在 项目 settings.py 初始化 DataBase（需要在七彩石或环境变量中配置初始化相关变量）fromfastflyer.databaseimportget_dataset_pool# 初始化 datasetclassDataBase:# 如果启用 MySQL 请取消注释db_user=getenv("flyer_db_user","root")db_pass=getenv("flyer_db_pass","")db_host=getenv("flyer_db_host","localhost")db_port=getenv("flyer_db_port",3306)db_name=getenv("flyer_db_name","flyer")db_chartset=getenv("flyer_db_chartset","utf8")db_recycle_rate=int(getenv("flyer_db_recycle_rate",900))db_pool_size=int(getenv("flyer_db_pool_size",32))data_set=get_dataset_pool(db_host,db_port,db_name,db_user,db_pass,db_recycle_rate,db_pool_size)data_set=get_dataset_pool(db_user,db_pass,db_host,db_port,db_name)table=data_set["表名"]# 具体逻辑代码文件：增删改查代码示例：fromdatasetimportTablefrom<app>.settingsimportDataBaseclassDemoClass:"""    演示代码    """def__init__(self)->None:# 定义为 Table，让IDE可以自动提示函数self.db_set:Table=DataBase.data_set["表名"]defupsert(self):"""        插入或更新数据        """row= {"key_item":0,"item1":1,"item2":2}self.db_set.upsert(row,keys=["key_item"])defupsert_many(self):"""        批量插入或更新数据        """row= [{"key_item":0,"item1":1,"item2":2}, {"key_item":1,"item1":2,"item2":3}]self.db_set.upsert_many(row,keys=["key_item"])defselect(self):"""        查询数据        """row= {"key_item":0,"item1":1,"item2":2}row["_limit"]=100row["_offset"]=0row["order_by"]="key_item"result=self.db_set.find(**row)data= [itemforiteminresult]print(data)defselect_one(self):"""        查询1条数据        """row= {"key_item":0,"item1":1,"item2":2}row["order_by"]="key_item"result=self.db_set.find_one(**row)print(result)defdelete(self):"""        删除数据        """row= {"key":"value"}result=self.db_set.delete(**row)ifresult==0:print("未匹配到数据")print(result)

环境变量

框架基础配置

Opentelemetry 配置

返回码

示例代码

fromfastflyerimportstatusfromfastflyer.schemasimportDataResponsefromfastflyerimportAPIRouterrouter=APIRouter(tags=["Demo示例"])@router.get("/demo",response_model=DataResponse,summary="Demo接口")asyncdefdemo(id:int):"""    演示接口：信息查询    ---    - 附加说明: 这是一个演示接口。    """return {"code":status.HTTP_200_OK,"data": {"itemId":id}}

返回码清单

正常类返回码：20x

跳转类返回码：30x

客户端错误返回码：40x

服务端错误返回码：50x

第三方服务错误返回码：60x

WebSocket状态码

如何加入