jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
docs/v1.0/architecture/adrs/009-resource-fixtures-separ...

5.1 KiB
Raw Permalink Blame History

ADR 009: 资源目录职责分离

状态

✅ 已接受 - 2026-02-02

背景

在项目开发过程中，发现资源目录结构存在以下问题：

  1. 职责不清：

    • app/resources/fixtures/ 定义为"测试数据/初始数据"
    • tests/fixtures/ 实际存储测试数据
    • 两者职责重叠，容易混淆

  2. 文档不一致：

    • 文档说明测试数据应在 app/resources/fixtures/
    • 实际测试数据在 tests/fixtures/screenplays/

  3. 打包问题：

    • 测试数据是否应该打包到生产环境？
    • 如何区分"种子数据"和"测试数据"？

  4. 冗余目录：

    • app/resources/docs/ 完全为空
    • FastAPI 已自动生成 API 文档
    • 项目文档统一在根目录 docs/

决策

采用明确分离策略，严格区分应用资源和测试数据：

1. 目录职责定义

app/resources/fixtures/ - 应用初始化数据（种子数据）

  • 用途：应用启动时加载的种子数据、配置数据
  • 示例：AI 模型配置、定价方案、演示项目
  • 特点：会被打包到生产环境 Docker 镜像
  • 访问：应用代码可访问

scripts/fixtures/ - 调试样本文件

  • 用途：手动调试脚本使用的样本文件
  • 示例：剧本样本文件（PDF、DOCX、PPTX）
  • 特点：不会被打包到生产环境（通过 .dockerignore 排除）
  • 访问：仅调试脚本访问

2. 删除冗余目录

删除 app/resources/docs/ 目录，理由：

  • FastAPI 自动生成 API 文档（/docs、/redoc）
  • 项目文档已在根目录 docs/ 统一管理
  • 当前完全为空，无实际用途
  • 符合 YAGNI 原则

3. 最终目录结构

server/
├── app/
│   ├── resources/              # 应用资源（提交 Git，打包到生产）
│   │   ├── templates/          # 邮件/短信模板
│   │   └── fixtures/           # 应用初始化数据（种子数据）
│   ├── uploads/                # 用户上传（不提交 Git）
│   └── storage/                # 本地存储（不提交 Git）
├── scripts/
│   └── fixtures/               # 调试样本（不提交 Git，不打包到生产）
│       └── screenplays/        # 剧本样本文件
└── tests/
    ├── unit/                   # 单元测试
    ├── integration/            # 集成测试
    └── conftest.py             # pytest 配置（代码定义的 fixtures）

理由

1. 符合社区惯例

  • Python/FastAPI 社区：pytest fixtures 是代码定义的测试辅助函数
  • 调试样本隔离：调试样本不应该被应用代码直接访问
  • 关注点分离：应用资源、调试样本、测试代码职责清晰

2. 生产环境优化

  • 减少镜像体积：调试样本不会被打包到 Docker 镜像
  • 安全性：调试样本不会暴露到生产环境
  • 性能：减少不必要的文件复制

3. 开发体验

  • 清晰的职责划分：开发者一眼就能区分资源类型
  • 易于维护：种子数据和调试样本分开管理
  • 避免混淆：不会误将调试样本当作种子数据

4. 文档一致性

  • 统一文档位置：项目文档在根目录 docs/
  • API 文档自动生成：FastAPI 自动生成，无需手动维护
  • 减少冗余：删除空目录，保持结构简洁

影响

正面影响

  1. 职责清晰：

    • 种子数据：应用初始化
    • 调试样本：手动调试

  2. 生产优化：

    • 镜像体积减小
    • 部署速度提升

  3. 开发效率：

    • 目录结构简洁
    • 易于理解和维护

负面影响

  1. 需要更新文档：

    • 更新 app/resources/README.md
    • 更新 RESOURCES.md
    • 新增 tests/fixtures/README.md

  2. 开发者认知：

    • 需要明确告知开发者两者的区别
    • 需要在文档中清晰说明

实施步骤

1. 更新文档

  • 更新 server/app/resources/README.md
  • 更新 server/RESOURCES.md
  • 新增 server/app/resources/fixtures/README.md
  • 新增 server/scripts/fixtures/README.md
  • 删除 server/tests/fixtures/ 目录（未使用）

2. 删除冗余目录

  • 删除 server/app/resources/docs/
  • 更新相关文档引用

3. 创建 ADR

  • 记录架构决策
  • 说明选择理由
  • 提供迁移指南

替代方案

方案 2：统一到 resources（已拒绝）

将所有测试数据移动到 app/resources/fixtures/

拒绝理由：

  • ❌ 测试数据会被打包到生产镜像（增加体积）
  • ❌ 违反"测试数据应该在 tests/ 目录"的惯例
  • ❌ 应用代码不应该依赖测试数据

参考资料

相关决策

作者: Jointo 开发团队
日期: 2026-02-02
状态: 已接受