技术文档

Appearance

项目架构说明 ​

本文档基于当前项目代码整理，说明目录结构、各文件用途、应用启动流程和配置加载方式。

1. 项目概览 ​

这是一个基于 FastAPI 的 Web 后端项目，目前处于基础骨架阶段。

  • Web 框架：FastAPI
  • ASGI 服务器：Uvicorn
  • 数据校验：Pydantic
  • 配置管理：Pydantic Settings
  • Python 版本：3.14，项目要求 Python >=3.14
  • 依赖管理：uv，通过 pyproject.toml 和 uv.lock 管理
  • 应用组织方式：公共配置按功能划分，业务代码按 book、sys 模块划分

当前已经实现：

  • FastAPI 应用工厂。
  • 开发、生产、测试三种启动入口。
  • 基于 APP_ENV 的多环境配置加载。
  • 一个用于查看当前环境配置的 GET /config 接口。

当前尚未实现：

  • book 和 sys 模块中的具体业务代码。
  • 业务路由在主应用中的注册。
  • 数据库连接、ORM 模型和数据库访问逻辑。
  • 自动化测试代码。

2. 整体目录结构 ​

text
demo1/
├── core/                         # 公共核心能力
│   └── config.py                 # 环境配置定义与加载
├── modules/                      # 业务模块根目录
│   ├── book/                     # 图书业务模块
│   │   ├── modules.py            # 当前为空的模块预留文件
│   │   ├── router.py             # 图书路由预留文件
│   │   ├── schemas.py            # 图书数据结构预留文件
│   │   └── service.py            # 图书业务逻辑预留文件
│   └── sys/                      # 系统业务模块
│       ├── modules.py            # 当前为空的模块预留文件
│       ├── router.py             # 系统路由预留文件
│       ├── schemas.py            # 系统数据结构预留文件
│       └── service.py            # 系统业务逻辑预留文件
├── .env                          # 默认环境配置
├── .env.dev                      # 开发环境配置
├── .env.prod                     # 生产环境配置
├── .env.test                     # 测试环境配置
├── .gitignore                    # Git 忽略规则
├── .python-version               # 项目使用的 Python 版本
├── ARCHITECTURE.md               # 项目架构说明，即本文档
├── README.md                     # 项目说明文件，当前为空
├── main.py                       # 应用创建、接口定义和启动入口
├── pyproject.toml                # 项目元数据、依赖和命令入口
└── uv.lock                       # uv 生成的依赖锁定文件

此外，项目目录中存在 .venv/，它是本地 Python 虚拟环境，包含解释器、启动脚本和第三方依赖。该目录由工具自动生成，不属于业务源码，因此不逐一说明其内部文件，也不应手动修改。

3. 分层与模块职责 ​

3.1 应用入口层：main.py ​

负责把项目运行起来，主要包括：

  1. 通过 create_app() 创建并配置 FastAPI 实例。
  2. 在应用工厂中延迟导入配置，确保启动函数已经设置 APP_ENV。
  3. 定义当前的 GET /config 接口。
  4. 通过 _start() 设置环境、监听地址、端口和重载行为。
  5. 提供 dev()、prod()、test() 三个命令入口。

3.2 核心配置层：core/ ​

目前只包含配置管理，不负责业务逻辑。

core/config.py 使用 BaseSettings 定义配置字段，并在模块导入时创建全局 settings 对象。应用通过该对象读取应用名称、环境、调试开关和数据库地址。

3.3 业务模块层：modules/ ​

业务代码按照领域划分为：

  • book：图书相关业务。
  • sys：系统相关业务。

两个模块目前具有相同的文件骨架，但所有文件均为空，也没有被 main.py 导入或注册。因此，它们目前只表示目录设计，不参与应用运行。

按照常见的 FastAPI 分层方式，这些预留文件可分别承担以下职责：

文件类型规划职责当前状态
router.py定义 APIRouter、HTTP 路径、请求参数和响应模型空文件，未实现
schemas.py定义 Pydantic 请求、响应及数据传输结构空文件，未实现
service.py承载业务规则、业务流程及数据访问协调空文件，未实现
modules.py模块内的预留文件；当前没有代码，无法从现有实现确定更具体的用途空文件，未实现

4. 每个文件的用途 ​

4.1 根目录文件 ​

文件用途
main.py项目主入口。包含 FastAPI 应用工厂、/config 接口，以及开发、生产、测试三种 Uvicorn 启动函数。
pyproject.toml定义项目名称、版本、Python 版本要求、直接依赖、命令入口和 setuptools 构建配置。dev、prod、test 分别指向 main.py 中的同名函数。
uv.lock由 uv 自动生成和维护，锁定直接及间接依赖的准确版本、来源和校验信息，用于可重复安装；通常不应手动编辑。
.python-version指定项目使用的 Python 版本，当前为 3.14。
.gitignore指定 Git 应忽略的内容，目前包括 Python 缓存、构建产物、包信息以及 .venv 虚拟环境。
.env默认配置文件，提供应用名称、环境名称、调试开关和数据库连接字符串等基础值。
.env.dev开发环境配置，在 APP_ENV=dev 时与 .env 一起加载，用于覆盖开发环境所需的配置。
.env.prod生产环境配置，在 APP_ENV=prod 时加载；当前将调试模式关闭，并使用生产环境对应的应用配置。
.env.test测试环境配置，在 APP_ENV=test 时加载，用于隔离测试环境配置。
README.md项目说明文档，当前为空，尚未提供安装、启动或使用说明。
ARCHITECTURE.md当前架构文档，记录目录结构、文件职责、启动流程和配置加载方式。

4.2 核心配置目录 ​

文件用途
core/config.py从进程环境变量读取 APP_ENV，依次配置 .env 和对应环境的 .env.<环境> 文件，定义并实例化 Settings。

Settings 当前包含以下字段：

配置字段对应环境变量用途
app_nameAPP_NAME作为 FastAPI 应用的 title。
app_envAPP_ENV标识当前环境，并由 /config 接口返回。
debugDEBUG控制 FastAPI 的 debug 参数。
database_urlDATABASE_URL保存数据库连接字符串；目前仅用于配置读取和 /config 返回，尚未建立数据库连接。

4.3 图书业务模块 ​

文件用途
modules/book/modules.py当前为空的图书模块预留文件，尚无任何实现。
modules/book/router.py预留给图书相关 HTTP 路由；当前为空，未注册到 FastAPI 应用。
modules/book/schemas.py预留给图书相关 Pydantic 数据结构；当前为空。
modules/book/service.py预留给图书相关业务逻辑；当前为空。

4.4 系统业务模块 ​

文件用途
modules/sys/modules.py当前为空的系统模块预留文件，尚无任何实现。
modules/sys/router.py预留给系统相关 HTTP 路由；当前为空，未注册到 FastAPI 应用。
modules/sys/schemas.py预留给系统相关 Pydantic 数据结构；当前为空。
modules/sys/service.py预留给系统相关业务逻辑；当前为空。

5. 应用启动流程 ​

5.1 启动入口 ​

pyproject.toml 注册了三个命令：

命令调用函数环境监听地址端口自动重载
uv run devmain:devdev127.0.0.18000开启
uv run prodmain:prodprod0.0.0.08000关闭
uv run testmain:testtest127.0.0.18000关闭

5.2 启动调用链 ​

text
dev / prod / test 命令
        ↓
main.py 中对应的启动函数
        ↓
_start(environment)
        ↓
设置进程环境变量 APP_ENV
        ↓
Uvicorn 以工厂模式加载 main:create_app
        ↓
create_app() 内延迟导入 core.config.settings
        ↓
读取默认配置和当前环境配置，创建 Settings 对象
        ↓
使用 APP_NAME 和 DEBUG 创建 FastAPI 应用
        ↓
注册 /config 接口并开始监听请求

create_app() 是应用工厂，Uvicorn 通过 factory=True 调用它获得真正的 FastAPI 实例。配置采用延迟导入，是为了让 _start() 先设置 APP_ENV，再初始化 Settings。

6. 配置加载机制 ​

core/config.py 使用以下两个配置文件来源：

text
.env
.env.${APP_ENV}

例如，执行开发环境启动命令后：

text
APP_ENV=dev
        ↓
加载 .env
        ↓
加载 .env.dev
        ↓
生成 settings

配置规则如下：

  • 选择哪个环境文件，取决于进程环境变量 APP_ENV。
  • .env 中的 APP_ENV 会作为配置字段被读取，但不能替代启动前对进程环境变量的设置，因为代码首先执行的是 os.environ["APP_ENV"]。
  • 多个 env 文件中存在同名字段时，后加载的环境专属文件可以覆盖默认文件中的值。
  • 操作系统环境变量的优先级高于 env 文件。
  • 配置中未声明的额外字段会被忽略，因为设置了 extra="ignore"。
  • 缺少必填配置或配置类型不正确时，Settings() 初始化会失败。

7. 当前接口与请求链路 ​

目前项目只定义了一个业务外的配置查看接口：

方法路径功能
GET/config返回当前环境名称和数据库连接字符串。

请求链路为：

text
客户端请求 GET /config
        ↓
FastAPI 路由匹配到 main.py 中的 index()
        ↓
读取全局 settings.app_env 和 settings.database_url
        ↓
返回 JSON 响应

响应结构为：

json
{
  "environment": "当前环境名称",
  "database_url": "当前数据库连接字符串"
}

book 和 sys 模块目前没有任何已注册接口，因此还不存在这些模块的实际请求处理链路。

8. 当前架构关系总结 ​

text
main.py
├── 使用 core.config.settings 创建 FastAPI 应用
├── 提供 GET /config
└── 提供 dev / prod / test 启动入口

core/config.py
├── 读取进程中的 APP_ENV
├── 加载 .env 与对应环境文件
└── 创建全局 settings

modules/book/*
└── 空文件，预留图书业务结构，尚未接入主应用

modules/sys/*
└── 空文件，预留系统业务结构，尚未接入主应用

整体来看，项目当前是一个“应用入口 + 多环境配置 + 业务模块预留目录”的 FastAPI 骨架。现阶段实际运行逻辑集中在 main.py 和 core/config.py，其余业务模块尚未进入请求处理流程。

网站备案号:津ICP备15001525号-2