agilelabs-fx-docs main topics/project-layout.md

项目目录规划

本页给出 AgileLabs 项目常见仓库结构的建议方案，重点帮助团队快速对齐目录边界、交接方式与 CI 落点。它是专题页，不是正式强制规范；不同类型项目可以按实际情况调整，但建议把原因和边界写进仓库文档。

适用场景

  • 客户端应用仓库。
  • 前后端全栈仓库。
  • 基础库、模板仓库、纯后端服务等特殊结构仓库。

推荐默认

  • 大多数新项目优先采用 backend/、frontend/、planning/ 三个目录。
  • Drone CI 配置优先放在仓库根目录 .drone.yml。
  • 前端源码目录与后端托管目录分开，避免把“开发目录”和“发布目录”混在一起。
  • 如果项目不适合这个默认结构，也应在 README 或项目文档里明确说明为什么偏离。

目录示例一：客户端应用仓库

客户端应用通常以前端或桌面端构建为主，不需要为了形式统一强行补一个空的 backend/。

repo-root
├─ frontend
│  ├─ src
│  ├─ public
│  ├─ dist
│  └─ package.json
├─ planning
│  ├─ prd.md
│  ├─ milestones.md
│  └─ release-notes.md
├─ scripts
│  └─ ci
│     ├─ mac-release.sh
│     └─ windows-release.ps1
├─ .drone.yml
└─ README.md
  • frontend/ 负责客户端源码、依赖与打包配置。
  • planning/ 负责需求、版本规划、设计说明和发布记录。
  • scripts/ci/ 适合放平台构建脚本、签名脚本、上传脚本等交付脚本。
  • .drone.yml 统一描述打包、校验、上传等发布流程，接手时更容易定位。

如果项目是桌面端或多平台客户端，CI 通常更像“按平台拆流水线”：

  • Windows、macOS、Linux 各自独立准备环境并执行打包。
  • 构建结果统一生成校验文件、版本文件或发布产物清单。
  • 上传、发布动作放在构建后置步骤，不和源码编译混写在一起。

目录示例二：前后端全栈仓库

大多数业务项目更适合下面这套默认结构：

repo-root
├─ backend
│  ├─ src
│  ├─ tests
│  ├─ ClientApp
│  ├─ Infrastructure
│  │  └─ Hosting
│  │     └─ Docker
│  │        └─ publish
│  └─ Backend.sln
├─ frontend
│  ├─ portalweb
│  ├─ adminweb
│  └─ helpdocsweb
├─ planning
│  ├─ prd.md
│  ├─ architecture.md
│  └─ milestones.md
├─ scripts
│  └─ frontend
│     └─ sync-all-apps-to-publish.sh
├─ .drone.yml
└─ README.md
  • backend/ 承担后端宿主、API、测试、发布目录和 ClientApp 承接点。
  • frontend/ 承担一个或多个前端源码目录，每个应用独立维护依赖与构建。
  • planning/ 承担 PRD、方案、架构说明、迭代计划和交接文档。
  • scripts/frontend/ 适合收口前端产物同步脚本，避免在 CI 里重复写复制逻辑。
  • 根目录 .drone.yml 统一表达整仓库交付流程，不把 CI 配置拆散到多个子目录。

这一类仓库的关键边界是：

  • 前端源码放在 frontend/，负责开发、构建和本地联调。
  • 后端托管目录放在 backend/ClientApp 或发布目录下，负责最终承接静态产物。
  • 前端构建产物最终通过同步脚本进入 backend/ClientApp/... 或 backend/Infrastructure/Hosting/Docker/publish/ClientApp/...。

如果项目需要通过 ASP.NET Core 宿主统一托管多个前端入口，继续阅读 前端托管。如果你想看联调与托管的最小样例目录，可以参考 fullstack-starter。

目录示例三：特殊仓库

不是所有仓库都应该机械套用同一份目录树。

  • 基础库或 SDK 仓库，通常只需要 src/、tests/、docs/。
  • 纯后端服务，通常可以只保留 backend/ 或直接使用 src/、tests/。
  • 模板仓库，可能会把可复制骨架、脚手架模板和生成器脚本放在同级目录。
  • 桌面客户端仓库，可能需要按平台拆 scripts/ci、签名配置和构建产物目录。

只要仓库结构偏离默认推荐，建议补充两件事：

  • 在仓库文档中写清楚为什么不使用默认结构。
  • 明确哪些目录负责源码、哪些目录负责发布、哪些目录只是脚本或规划资料。

CI 约定

根目录 .drone.yml 是默认推荐位置，因为它最容易表达“整个仓库如何交付”。

客户端应用仓库的 Drone 通常更偏向：

  • 按平台拆步骤或拆 pipeline。
  • 先准备环境和缓存，再执行客户端打包。
  • 最后执行校验、上传和发布。

全栈仓库的 Drone 通常更偏向：

  • 先做 runner 环境准备。
  • 多个前端应用并行构建。
  • 后端单独执行 dotnet publish。
  • 所有构建完成后统一汇总前端产物到发布目录或 ClientApp。
  • 最后再做镜像打包与部署。

这里推荐的是“阶段模式”，不是某个项目的固定写法。项目自己的 runner、镜像仓库、部署环境、命名空间和发布命令都应该保留在项目文档或项目配置里，不要写成通用默认值。更完整的说明可继续阅读 Drone CI 配置专题 与 Drone 配置参考索引。

常见坑

  • 同一个全栈仓库同时出现 apps/、src/、frontend/，但没有写清楚目录职责。
  • 前端源码目录和后端托管目录混在一起，导致开发目录、发布目录相互污染。
  • CI 配置散落在多个子目录，接手的人很难判断主流水线入口。
  • 把建议方案写成硬性规范，结果和真实项目边界冲突。
  • 只约定了目录名字，没有约定“谁负责源码、谁负责发布、谁负责规划”。

相关页面