python/fastapi_best_architecture
1
0
Fork 0
mirror of https://github.com/fastapi-practices/fastapi_best_architecture.git synced 2025-08-26 13:26:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update the README document (#214)

Browse Source
This commit is contained in:
Wu Clan
2023-09-25 16:51:05 +08:00
committed by GitHub
parent 5794cec94a
commit 10f5fa6198
2 changed files with 184 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
README.md
View File

@ -1,21 +1,25 @@
# FastAPI Best Architecture
[![GitHub](https://img.shields.io/github/license/fastapi-practices/fastapi_best_architecture)](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/LICENSE)
[![Static Badge](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
English | [简体中文](./README.zh-CN.md)
This is a base project for the FastAPI framework, using a pseudo three-tier architecture, **still in production**.
FastAPI framework based on the front-end and back-end separation of the middle and back-end solutions, follow
the [pseudo three-tier architecture](#pseudo-three-tier-architecture) design, support for **python3.10** and above
versions
It is intended to allow you to use it directly as your infrastructure to develop your project, this repository as a
template library public, can be used directly
Its purpose is to allow you to use it directly as the infrastructure of your new project, this repository as a template
library open to any person or enterprise can be used for free!
Support **python3.10** and above
**Continuously updated and maintained**
## Pseudo three-tier architecture
In python web frameworks, the mvc architecture is the most common, but for restful users, the three-tier architecture is
the way to go
The mvc architecture is a common design pattern in python web, but the three-tier architecture is even more fascinating.
But in python development, there is no universal standard for the concept of a three-tier architecture, so here I call
it a pseudo three-tier architecture
In python web development, there is no common standard for the concept of three-tier architecture, so we'll call it a
pseudo three-tier architecture here
| workflow | java | fastapi_best_architecture |
|----------------|----------------|---------------------------|
@ -25,23 +29,60 @@ it a pseudo three-tier architecture
| data access | dao / mapper | crud |
| model | model / entity | model |
## Online preview
Unfortunately, we don't have the funds to provide an online preview, you can deploy by checking
out [local-development](#local-development), or directly using [Docker](#docker-deploy)
to deploy, or at [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui)
See a preview of some of the screenshots
## Features
- [x] FastAPI new features
- [x] Asynchronous design
- [x] Restful API specification
- [x] SQLAlchemy 2.0 syntax
- [x] Pydantic data validation
- [x] Casbin RBAC permission control
- [x] APScheduler timed tasks
- [x] JWT authentication
- [x] Redis caching
- [x] Docker deployment
- [x] Pytest testing
- [x] Design with FastAPI PEP 593 Annotated Parameters
- [x] Global asynchronous design with async/await + asgiref
- [x] Follows Restful API specification
- [x] Global SQLAlchemy 2.0 syntax
- [x] Casbin RBAC access control model
- [x] APScheduler online timed tasks
- [x] JWT middleware whitelist authentication
- [x] Global customizable time zone time
- [x] Docker / Docker-compose deployment
- [x] Pytest Unit Testing
## Getting started:
TODO:
### 1: Legacy mode
1. [ ] Pydantic 2.0
## Built-in features
1. [x] User management: system user role management, permission assignment
2. [x] Department Management: Configure the system organization (company, department, group...)
3. [x] Menu Management: Configuration of system menus, user menus, button privilege identification
4. [x] Role Management: Assign role menu privileges, assign role routing privileges
5. [x] Dictionary Management: Maintain common fixed data or parameters within the system.
6. [x] Operation Logs: logging and querying of normal and abnormal system operations.
7. [x] Login Authentication: graphical authentication code background authentication login
8. [x] Login Logs: Logging and querying of normal and abnormal user logins
9. [x] Service Monitoring: server hardware device information and status
10. [x] Timed Tasks: online task control (modify, delete, pause...)
11. [x] Interface Documentation: Automatically generate online interactive API interface documentation.
TODO:
1. [ ] Dynamic Configuration: Dynamic configuration of the system environment (site title, logo, filing, footer...)
2. [ ] code generation: according to the table structure, visualize the generation of additions, deletions,
modifications and checks of the business code.
3. [ ] File Upload: Docking cloud OSS and local backup.
4. [ ] System Notification: proactively send timed task notifications, resource warnings, service anomaly warnings...
## Local development
* Python: 3.10+
* Mysql: 8.0+
* Redis: The latest stable version is recommended
* Nodejs: 14.0+
### BackEnd
1. Install dependencies
```shell
@ -74,13 +115,17 @@ it a pseudo three-tier architecture
# Execute the migration
alembic upgrade head
```
7. Execute the `backend/app/main.py` file to start the service
8. Browser access: http://127.0.0.1:8000/api/v1/docs
7. Modify the configuration file as needed
8. Execute the `backend/app/main.py` file to start the service
9. Browser access: http://127.0.0.1:8000/api/v1/docs
---
### 2: Docker
### Front
Click [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui) for details
### Docker deploy
1. Go to the directory where the ``docker-compose.yml`` file is located and create the environment variable
file ``.env``
@ -94,22 +139,25 @@ it a pseudo three-tier architecture
cp .env.docker .env
```
2. Execute the one-click boot command
2. Modify the configuration file as needed
3. Execute the one-click boot command
```shell
docker-compose up -d -build
```
3. Wait for the command to complete automatically
4. Visit the browser: http://127.0.0.1:8000/api/v1/docs
4. Wait for the command to complete automatically
5. Visit the browser: http://127.0.0.1:8000/api/v1/docs
## Test data
Initialize the test data using the `backend/sql/init_test_data.sql` file
## Development
## Development process
Development process, for reference only
For reference only
### BackEnd
1. Define the database model (model) and remember to perform database migration for each change
2. Define the data validation model (schema)
@ -117,9 +165,13 @@ Development process, for reference only
4. Define the business logic (service)
5. Write database operations (crud)
### Front
Click [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui) for details
## Test
Execute tests via pytest
Execute unittests via pytest
1. Create the test database `fba_test`, select utf8mb4 encoding
2. Enter the app directory
@ -141,30 +193,35 @@ Execute tests via pytest
<span style="margin: 0 5px;" ><a href="https://github.com/wu-clan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52145145?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
<span style="margin: 0 5px;" ><a href="https://github.com/downdawn" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/41266749?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
## Thanks
## Special thanks
- [FastAPI](https://fastapi.tiangolo.com/)
- [Pydantic](https://docs.pydantic.dev/latest/)
- [SQLAlchemy](https://docs.sqlalchemy.org/en/20/)
- [Casbin](https://casbin.org/zh/)
- [Ruff](https://beta.ruff.rs/docs/)
- ......
- [Black](https://black.readthedocs.io/en/stable/index.html)
- [RuoYi](http://ruoyi.vip/)
- ...
## Sponsor
## Sponsor us
> If this program has helped you, you can sponsor the author with some coffee beans :coffee:
> If this program has helped you, you can sponsor us with some coffee beans :coffee:
<table>
<tr>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/weixin.jpg?raw=true" width="180px"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/zfb.jpg?raw=true" width="180px"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/weixin.jpg?raw=true" width="180px" alt="WeChat"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/zfb.jpg?raw=true" width="180px" alt="Alipay"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/ERC20.jpg?raw=true" width="180px" alt="0x40D5e2304b452256afD9CE2d3d5531dc8d293138"/>
</tr>
<tr>
<td align="center">Wechat Pay</td>
<td align="center">WeChat Pay</td>
<td align="center">Ali Pay</td>
<td align="center">ERC20</td>
</tr>
</table>
## License
This project is licensed under the terms of the MIT license
This project is licensed under the terms of
the [MIT](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/LICENSE) license

124
README.zh-CN.md
View File

@ -1,18 +1,21 @@
# FastAPI 最佳架构
[![GitHub](https://img.shields.io/github/license/fastapi-practices/fastapi_best_architecture)](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/LICENSE)
[![Static Badge](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
简体中文 | [English](./README.md)
这是 FastAPI 框架的一个基础项目，使用伪三层架构，**目前还在制作中**
基于 FastAPI 框架的前后端分离中后台解决方案，遵循[伪三层架构](#伪三层架构)设计， 支持 **python3.10** 及以上版本
它的目的是让你可以直接用它作为你的基础架构来开发你的项目，本仓库作为模板库公开，可直接使用
它的目的是让你可以直接用它作为你新项目的基础架构，本仓库作为模板库公开，任何人或企业均可免费使用
支持 **python3.10** 及以上版本
**持续更新维护中**
## 伪三层架构
在 python 的 web 框架中，mvc 架构是最常见的，但是对于 restful 用户，三层架构是不二选择
mvc 架构作为常规设计模式，在 python web 中也很常见，但是三层架构更令人着迷
但是在 python 开发中，三层架构的概念并没有通用标准，所以这里我称之为伪三层架构
在 python web 开发中，三层架构的概念并没有通用标准，所以这里我们称之为伪三层架构
| 工作流程 | java | fastapi_best_architecture |
|------|----------------|---------------------------|
@ -24,21 +27,56 @@
## 特征
- [x] FastAPI 新特性
- [x] 异步设计
- [x] Restful API 规范
- [x] SQLAlchemy 2.0 语法
- [x] Pydantic 数据验证
- [x] Casbin RBAC 权限控制
- [x] APScheduler 定时任务
- [x] JWT 认证
- [x] Redis 缓存
- [x] Docker 部署
- [x] Pytest 测试
- [x] 使用 FastAPI PEP 593 Annotated 参数设计
- [x] async/await + asgiref 的全局异步设计
- [x] 遵循 Restful API 规范
- [x] 全局 SQLAlchemy 2.0 语法
- [x] Casbin RBAC 访问控制模型
- [x] APScheduler 在线定时任务
- [x] JWT 中间件白名单认证
- [x] 全局自定义时区时间
- [x] Docker / Docker-compose 部署
- [x] Pytest 单元测试
## 开始：
TODO:
### 1：传统模式
1. [ ] Pydantic 2.0
## 内置功能
1. [x] 用户管理：系统用户角色管理，权限分配
2. [x] 部门管理：配置系统组织机构（公司、部门、小组...）
3. [x] 菜单管理：配置系统菜单，用户菜单，按钮权限标识
4. [x] 角色管理：角色菜单权限分配，角色路由权限分配
5. [x] 字典管理：维护系统内部常用固定数据或参数
6. [x] 操作日志：系统正常操作和异常操作日志记录和查询
7. [x] 登录认证：图形验证码后台认证登录
8. [x] 登录日志：用户正常登录和异常登录的日志记录与查询
9. [x] 服务监控：服务器硬件设备信息与状态
10. [x] 定时任务：在线任务控制（修改，删除，暂停...）
11. [x] 接口文档：自动生成在线交互式 API 接口文档
TODO:
1. [ ] 动态配置：对系统环境进行动态配置（网站标题，LOGO，备案，页脚...）
2. [ ] 代码生成：根据表结构，可视化生成增删改查业务代码
3. [ ] 文件上传：对接云OSS加本地备份
4. [ ] 系统通知：主动发送定时任务通知，资源警告，服务异常预警...
## 在线预览
遗憾的是，我们没有资金提供在线预览，您可以通过查看[本地开发](#本地开发)进行部署，或直接使用 [Docker](#docker-部署)
进行部署，或者在 [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui)
查看部分截图预览
## 本地开发
* Python 3.10+
* Mysql 8.0+
* Redis 推荐最新稳定版
* Nodejs 14.0+
### 后端
1. 安装依赖项
```shell
@ -72,12 +110,17 @@
alembic upgrade head
```
7. 执行 `backend/app/main.py` 文件启动服务
8. 浏览器访问：http://127.0.0.1:8000/api/v1/docs
7. 按需修改配置文件
8. 执行 `backend/app/main.py` 文件启动服务
9. 浏览器访问：http://127.0.0.1:8000/api/v1/docs
---
### 2：Docker
### 前端
点击 [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui) 查看详情
### Docker 部署
1. 进入 `docker-compose.yml` 文件所在目录，创建环境变量文件`.env`
@ -90,24 +133,25 @@
cp .env.docker .env
```
2. 执行一键启动命令
2. 按需修改配置文件
3. 执行一键启动命令
```shell
docker-compose up -d -build
```
3. 等待命令自动完成
4. 浏览器访问：http://127.0.0.1:8000/api/v1/docs
4. 等待命令自动完成
5. 浏览器访问：http://127.0.0.1:8000/api/v1/docs
## 测试数据
[//]: # (执行 `backend/app/init_test_data.py` 文件，自动创建测试数据)
使用 `backend/sql/init_test_data.sql` 文件初始化测试数据
## 开发
## 开发流程
开发流程，仅供参考
仅供参考
### 后端：
1. 定义数据库模型（model），每次变化记得执行数据库迁移
2. 定义数据验证模型（schema）
@ -115,9 +159,13 @@
4. 定义业务逻辑（service）
5. 编写数据库操作（crud）
### 前端
点击 [fastapi_best_architecture_ui](https://github.com/fastapi-practices/fastapi_best_architecture_ui) 查看详情
## 测试
通过 pytest 执行测试
通过 pytest 执行单元测试
1. 创建测试数据库 `fba_test`，选择 utf8mb4 编码
2. 进入app目录
@ -139,30 +187,34 @@
<span style="margin: 0 5px;" ><a href="https://github.com/wu-clan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52145145?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
<span style="margin: 0 5px;" ><a href="https://github.com/downdawn" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/41266749?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
## 鸣谢
## 特别鸣谢
- [FastAPI](https://fastapi.tiangolo.com/)
- [Pydantic](https://docs.pydantic.dev/latest/)
- [SQLAlchemy](https://docs.sqlalchemy.org/en/20/)
- [Casbin](https://casbin.org/zh/)
- [Ruff](https://beta.ruff.rs/docs/)
- ......
- [Black](https://black.readthedocs.io/en/stable/index.html)
- [RuoYi](http://ruoyi.vip/)
- ...
## 赞助
## 赞助我们
> 如果此项目能够帮助到你，你可以赞助作者一些咖啡豆表示鼓励 :coffee:
> 如果此项目能够帮助到你，你可以赞助我们一些咖啡豆表示鼓励 :coffee:
<table>
<tr>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/weixin.jpg?raw=true" width="180px"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/zfb.jpg?raw=true" width="180px"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/weixin.jpg?raw=true" width="180px" alt="Wechat"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/zfb.jpg?raw=true" width="180px" alt="Alipay"/>
<td><img src="https://github.com/wu-clan/image/blob/master/pay/ERC20.jpg?raw=true" width="180px" alt="0x40D5e2304b452256afD9CE2d3d5531dc8d293138"/>
</tr>
<tr>
<td align="center">微信</td>
<td align="center">支付宝</td>
<td align="center">ERC20</td>
</tr>
</table>
## 许可证
本项目根据 MIT 许可证的条款进行许可
本项目根据 [MIT](https://github.com/fastapi-practices/fastapi_best_architecture/blob/master/LICENSE) 许可证的条款进行许可