gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-08-02 21:57:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: references - add enterprise architecture template

Browse Source
This commit is contained in:
tukuaiai
2026-05-26 00:15:59 +08:00
parent 4d0d8620a4
commit bb11623a6d
1 changed files with 758 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/references/README.md
+758
View File
@@ -16,6 +16,7 @@
|:---|:---|
| 新项目结构怎么搭 | [项目架构模板](#reference-engineering-practice-1-项目架构模板) |
| Python 项目骨架怎么搭 | [通用 Python 项目骨架](#reference-engineering-practice-通用-python-项目骨架) |
| 企业级项目架构怎么搭 | [企业级 Monorepo / Multi-repo 项目架构标准模板](#reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板) |
| AI 代码质量怎么卡住 | [AI 编程质量门禁与常见坑](#quality-gates) |
| 系统提示词怎么写 | [系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则) |
| 强前置条件怎么约束 | [强前置条件约束](#reference-engineering-practice-2-强前置条件约束) |
@@ -41,6 +42,7 @@
- [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构)
- [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构)
- [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构)
- [企业级 monorepo / multi-repo 项目架构标准模板](#reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板)
- [6. Full-Stack Web 应用结构](#reference-engineering-practice-6-full-stack-web-应用结构)
- [7. Dataset First 数据服务结构](#reference-engineering-practice-7-dataset-first-数据服务结构)
- [一句话](#reference-engineering-practice-一句话)
@@ -424,6 +426,7 @@
| Web API / 后端服务 | Python Web/API 项目结构 |
| 数据分析 / 量化 / 机器学习 | 数据科学项目结构 |
| 多服务 / 大型系统 | Monorepo 项目结构 |
| 中大型工程组织 / 平台工程 / 多产品线 | 企业级 Monorepo / Multi-repo 项目架构标准模板 |
| 前后端一体项目 | Full-Stack Web 应用结构 |
| 长期运行的数据采集服务 | Dataset First 数据服务结构 |
@@ -1288,6 +1291,761 @@ project-monorepo/
- `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。
- 顶层脚本只做编排，不隐藏服务内部逻辑。
<a id="reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板"></a>
#### 企业级 monorepo / multi-repo 项目架构标准模板
版本：v1.0
定位：共识级企业参考模型
适用：中大型工程组织、平台工程、技术中台、多产品线、AI / 数据 / 云原生系统
---
##### 1. 总体原则
企业级项目架构不应只按“前端 / 后端 / 基础设施 / 文档”粗分，而应按以下几类长期稳定的企业真相划分：
| 顶层目录 | 核心职责 | 真相类型 |
| -------------------- | ------------------------------------ | ------- |
| `governance/` | 标准、Owner、ADR、SLO、风险、复盘、门禁 | 规则与演进真相 |
| `contracts/` | API、事件、Schema、数据集、资源、策略 | 跨层契约真相 |
| `catalog/` | 系统、组件、资源、Owner、生命周期 | 软件资产真相 |
| `infra/` | 基础设施、运行、交付、观测、安全、成本 | 运行底座真相 |
| `internal-platform/` | 内部开发者平台、模板、自助化、门户 | 开发者体验真相 |
| `middle-platform/` | 数据、API、计算、AI、消息、身份等复用能力 | 技术中台能力 |
| `products/` | Web、Mobile、Bot、Admin、Reporting 等产品入口 | 用户价值交付 |
| `shared/` | 极薄共享库、SDK、测试夹具 | 低层复用能力 |
> 最终模型：
> **governance + contracts + catalog + infra + internal-platform + middle-platform + products**
> `shared/` 是辅助层，不应膨胀成新的业务中台。
---
##### 2. 推荐目录结构
```text
repo/
├── governance/ # 治理真相：标准、owner、ADR、SLO、风险、复盘、门禁
│ ├── standards/ # 工程标准、安全标准、代码规范、架构原则
│ ├── decisions/ # ADR：Architecture Decision Records
│ ├── ownership/ # Owner、RACI、值班、升级路径
│ ├── slo/ # SLI、SLO、error budget、服务等级目标
│ ├── risks/ # 风险登记、威胁模型、合规风险
│ ├── gates/ # 发布门禁、安全门禁、质量门禁
│ └── postmortems/ # 事故复盘、行动项、长期修复
│
├── contracts/ # 机器可读契约：跨层边界的唯一真相
│ ├── apis/ # OpenAPI、GraphQL schema、RPC IDL
│ ├── events/ # AsyncAPI、事件定义、topic、订阅约定
│ ├── schemas/ # JSON Schema、Proto、Avro、Parquet schema
│ ├── datasets/ # 数据集契约、数据产品、质量规则、血缘
│ ├── resources/ # 云资源、K8s CRD、Terraform module interface
│ └── policies/ # OPA、Rego、IAM policy、数据访问策略
│
├── catalog/ # 软件资产目录：系统、组件、资源、API、owner、生命周期
│ ├── systems/ # System 定义：产品域、平台域、业务系统
│ ├── components/ # Component 定义：服务、库、任务、前端应用
│ ├── resources/ # Resource 定义：DB、queue、bucket、cache、cluster
│ ├── domains/ # Domain 定义：业务域、技术域、平台域
│ └── scorecards/ # 健康度、成熟度、安全、可靠性评分
│
├── infra/ # 基础设施与运行底座
│ ├── control-plane/ # 拓扑、生命周期、状态控制、cluster management
│ ├── resource-plane/ # compute、network、storage、database、queue
│ ├── runtime-plane/ # worker、daemon、job、scheduler、queue consumer
│ ├── delivery-plane/ # CI/CD、制品、发布、回滚、环境提升
│ ├── observability/ # logs、metrics、traces、health、alerts、dashboards
│ ├── security/ # secrets、IAM、policy enforcement、audit
│ ├── environments/ # local、dev、staging、production、dr
│ ├── disaster-recovery/ # backup、restore、runbook、演练
│ └── cost/ # FinOps、预算、资源归属、成本归因
│
├── internal-platform/ # 内部开发者平台 IDP，不等于业务中台
│ ├── portal/ # Backstage 类开发者入口
│ ├── templates/ # golden paths、脚手架、服务模板
│ ├── orchestration/ # provision、workflow、automation
│ ├── developer-tools/ # CLI、SDK、诊断工具、本地开发工具
│ ├── scorecards/ # 服务健康、质量、安全、成熟度评分
│ └── docs/ # 平台用户文档、接入指南、FAQ
│
├── middle-platform/ # 技术中台：业务无关、产品复用的公共能力
│ ├── data-platform/ # ingestion、quality、lineage、catalog、serving
│ ├── api-platform/ # gateway、query、auth、rate limit、schema
│ ├── compute-platform/ # batch、stream、derived jobs、task execution
│ ├── ai-platform/ # LLM、prompt、tool、context、eval、agent runtime
│ ├── messaging-platform/ # notification、event、subscription、push
│ ├── integration-platform/ # external API、webhook、provider adapter
│ ├── identity-platform/ # account、authn、authz、tenant
│ ├── search-platform/ # indexing、retrieval、ranking
│ └── experimentation-platform/ # A/B、feature flag、experiment metrics
│
├── products/ # 产品与渠道，直接面向用户或业务场景
│ ├── web/ # Web 产品
│ ├── mobile/ # 移动端产品
│ ├── bot/ # Bot、Agent、Chat 入口
│ ├── admin/ # 管理后台、运营后台
│ └── reporting/ # 报表、BI、经营分析入口
│
├── shared/ # 极薄共享库，只放真正跨域复用的低层代码
│ ├── libraries/ # 通用基础库
│ ├── sdks/ # 对外或内部 SDK
│ └── test-fixtures/ # 跨域测试夹具
│
├── tools/ # 仓库级工具：codegen、lint、verify、migration helpers
├── docs/ # 文档入口，不替代 governance/contracts/catalog
└── ci/ 或 .github/ # CI workflow 入口
```
---
##### 3. 顶层目录职责说明
##### 3.1 `governance/`：规则与演进真相
用于承载组织级工程治理，不放业务代码。
应包含：
```text
governance/
├── standards/
│ ├── engineering-standard.md
│ ├── security-standard.md
│ ├── data-standard.md
│ └── api-standard.md
├── decisions/
│ └── adr-0001-record-template.md
├── ownership/
│ ├── owners.yaml
│ └── escalation-policy.md
├── slo/
│ ├── slo-template.yaml
│ └── error-budget-policy.md
├── risks/
│ └── risk-register.yaml
├── gates/
│ ├── release-gate.yaml
│ ├── security-gate.yaml
│ └── architecture-gate.yaml
└── postmortems/
└── postmortem-template.md
```
核心规则：
* 架构决策必须进入 `decisions/`
* Owner 与升级路径必须进入 `ownership/`
* 生产系统必须定义 SLO
* 事故必须有复盘和行动项
* 发布、安全、质量门禁应机器可执行
---
##### 3.2 `contracts/`：跨层契约真相
用于放置机器可读契约，避免接口、事件、数据模型散落在代码注释或文档里。
推荐结构：
```text
contracts/
├── apis/
│ ├── public/
│ ├── internal/
│ └── partner/
├── events/
│ ├── topics/
│ └── schemas/
├── schemas/
│ ├── json/
│ ├── proto/
│ └── avro/
├── datasets/
│ ├── data-products/
│ ├── quality-rules/
│ └── lineage/
├── resources/
│ ├── terraform-modules/
│ ├── kubernetes-crds/
│ └── cloud-resources/
└── policies/
├── iam/
├── opa/
└── data-access/
```
核心规则：
* API 变更必须先更新契约
* 事件字段变更必须兼容旧消费者
* Dataset 必须声明 owner、schema、质量规则、生命周期
* Policy 应尽量机器可执行
* 契约变更必须进入 CI 校验
---
##### 3.3 `catalog/`：软件资产真相
用于记录系统、组件、资源、API、Domain、Owner、Lifecycle。
推荐结构：
```text
catalog/
├── systems/
│ └── payment-system.yaml
├── components/
│ └── payment-api.yaml
├── resources/
│ └── payment-db.yaml
├── domains/
│ └── finance-domain.yaml
└── scorecards/
├── production-readiness.yaml
├── security-scorecard.yaml
└── reliability-scorecard.yaml
```
每个资产建议至少包含：
```yaml
name: payment-api
type: service
system: payment-system
domain: finance
owner: team-payment
lifecycle: production
tier: tier-1
dependsOn:
- resource:payment-db
- api:identity-api
providesApis:
- payment-public-api
consumesApis:
- identity-internal-api
slo:
availability: 99.9
latency_p95_ms: 300
```
核心规则：
* 没有 owner 的系统不允许进入生产
* 没有 catalog 的服务不应接入发布流水线
* 资源必须能追溯到系统、团队和成本中心
* Lifecycle 必须明确：experimental、development、production、deprecated、retired
---
##### 3.4 `infra/`：基础设施与运行底座
`infra/` 负责运行、交付、安全、观测、灾备和成本，不承载业务逻辑。
推荐结构：
```text
infra/
├── control-plane/
├── resource-plane/
├── runtime-plane/
├── delivery-plane/
├── observability/
├── security/
├── environments/
│ ├── local/
│ ├── dev/
│ ├── staging/
│ ├── production/
│ └── dr/
├── disaster-recovery/
└── cost/
```
核心规则：
* 环境配置必须显式分离
* 生产变更必须可审计、可回滚
* 关键资源必须有备份、恢复方案和演练记录
* 观测能力应覆盖 logs、metrics、traces、alerts、dashboards
* 成本必须能归因到 owner、system、environment
---
##### 3.5 `internal-platform/`：内部开发者平台
这是 IDP，不是业务中台。它服务的是内部开发者，目标是降低交付复杂度。
推荐结构：
```text
internal-platform/
├── portal/
├── templates/
├── orchestration/
├── developer-tools/
├── scorecards/
└── docs/
```
典型能力：
* 服务创建模板
* Golden path
* 自助资源申请
* 服务注册
* CI/CD 接入
* 发布操作入口
* 服务健康评分
* 诊断工具
* 开发者文档
核心规则：
* 不能把业务能力塞进 `internal-platform/`
* 模板应默认符合治理、安全、观测、发布标准
* 平台能力要以产品方式运营，有 adoption、usage、feedback、SLO
---
##### 3.6 `middle-platform/`：技术中台
技术中台是可被多个产品复用的公共技术能力，不直接面向最终业务场景交付。
推荐结构：
```text
middle-platform/
├── data-platform/
├── api-platform/
├── compute-platform/
├── ai-platform/
├── messaging-platform/
├── integration-platform/
├── identity-platform/
├── search-platform/
└── experimentation-platform/
```
各平台职责：
| 子平台 | 职责 |
| --------------------------- | ------------------------------------------ |
| `data-platform/` | 数据采集、质量、血缘、目录、服务化 |
| `api-platform/` | Gateway、认证、限流、Schema、查询层 |
| `compute-platform/` | Batch、Stream、任务调度、派生计算 |
| `ai-platform/` | LLM、Prompt、Tool、Context、Eval、Agent Runtime |
| `messaging-platform/` | 通知、事件、订阅、Push |
| `integration-platform/` | 外部 API、Webhook、Provider Adapter |
| `identity-platform/` | Account、AuthN、AuthZ、Tenant |
| `search-platform/` | 索引、召回、排序、检索 |
| `experimentation-platform/` | A/B、Feature Flag、实验指标 |
核心规则：
* 可以依赖 `infra/`
* 可以暴露能力给 `products/`
* 不应依赖 `products/`
* 不应承载某个单一产品的专属业务逻辑
* 能力必须产品化：契约、文档、SLO、Owner、接入方式都要明确
---
##### 3.7 `products/`：产品与渠道
产品层直接面向用户或具体业务场景。
推荐结构：
```text
products/
├── web/
├── mobile/
├── bot/
├── admin/
└── reporting/
```
核心规则：
* 产品可以消费 `middle-platform/` 暴露的能力
* 产品可以使用 `internal-platform/` 提供的开发、发布、自助能力
* 产品不应直接绕过契约访问底层资源
* 产品特有逻辑留在产品内，不要污染中台
* 多产品复用前，先证明确实跨产品稳定复用
---
##### 3.8 `shared/`：极薄共享层
`shared/` 是最容易变成垃圾桶的目录，必须严格限制。
允许放：
```text
shared/
├── libraries/
├── sdks/
└── test-fixtures/
```
适合放：
* 无业务语义的基础库
* SDK
* 类型工具
* 通用测试夹具
* Codegen runtime
* 跨域稳定协议适配
不适合放：
* 业务规则
* 产品流程
* 领域模型
* 随手抽出来的 common helper
* 只有两个调用方的临时共享逻辑
核心规则：
> `shared/` 必须薄。
> 一旦它开始承载业务语义，就说明边界设计已经失控。
---
##### 4. 跨层依赖规则
推荐依赖方向：
```text
products
↓
middle-platform
↓
infra
internal-platform
↓
infra
contracts ← 被所有层引用
catalog ← 被所有层注册
governance ← 约束所有层
shared ← 仅提供极薄低层复用
```
##### 强制边界规则
| 规则 | 说明 |
| ------------------------------------------------------------- | ----------------------------------------------- |
| `products` 只能消费 `middle-platform` / `internal-platform` 暴露的接口 | 不直接绕过契约访问底层资源 |
| `middle-platform` 可以依赖 `infra` | 但不能依赖 `products` |
| `internal-platform` 服务开发者 | 不承载业务领域能力 |
| `infra` 不写业务逻辑 | 只负责运行、交付、安全、观测、成本 |
| `contracts` 是跨层接口真相 | API、event、schema、dataset、resource、policy 都应机器可读 |
| `catalog` 是资产和 owner 真相 | 系统、组件、资源、Owner、Lifecycle 必须可查 |
| `governance` 是规则和演进真相 | 标准、ADR、SLO、复盘、门禁不可散落 |
| `shared` 必须极薄 | 不允许变成 `common` 垃圾桶 |
---
##### 5. 推荐门禁
##### 5.1 架构门禁
进入生产前必须满足：
```text
- 已登记 catalog
- 已指定 owner
- 已定义 lifecycle
- 已声明依赖关系
- 已定义 API / event / dataset / resource 契约
- 已有最小 SLO
- 已有日志、指标、追踪或健康检查
- 已有发布与回滚方案
- 已通过安全基线检查
```
##### 5.2 契约门禁
```text
- API schema 校验
- Event schema 兼容性校验
- Dataset schema 兼容性校验
- Policy 语法校验
- Breaking change 检测
- Consumer impact 分析
```
##### 5.3 运行门禁
```text
- Health check
- Readiness check
- Alert rule
- Dashboard
- Error budget
- Runbook
- Backup policy
- Rollback policy
```
---
##### 6. 每个服务的推荐最小结构
适用于 `products/` 或 `middle-platform/` 下的具体服务。
```text
service-name/
├── src/
├── tests/
├── configs/
│ ├── local/
│ ├── dev/
│ ├── staging/
│ └── production/
├── docs/
│ ├── README.md
│ ├── runbook.md
│ └── troubleshooting.md
├── deploy/
│ ├── helm/
│ ├── kustomize/
│ └── terraform/
├── contracts/
│ └── README.md # 本服务私有契约说明，正式契约仍进入 repo/contracts
├── catalog-info.yaml
├── CODEOWNERS
└── README.md
```
服务级 README 建议包含：
```text
#### Service Name
##### Purpose
这个服务解决什么问题。
##### Owner
团队、负责人、值班与升级路径。
##### Runtime
运行方式、依赖、端口、环境变量。
##### Contracts
提供哪些 API、事件、数据集或资源。
##### Dependencies
依赖哪些服务、资源、外部系统。
##### SLO
可用性、延迟、错误率、吞吐等目标。
##### Observability
日志、指标、追踪、Dashboard、告警。
##### Deployment
发布方式、回滚方式、环境提升规则。
##### Runbook
常见故障、排查步骤、恢复步骤。
##### Lifecycle
experimental / development / production / deprecated / retired。
```
---
##### 7. 成熟度分阶段落地
不建议一开始就把所有目录做满。更现实的落地方式是分阶段推进。
##### Phase 1：最小企业可用
先落地：
```text
governance/
contracts/
catalog/
infra/
products/
shared/
```
必须具备：
```text
- Owner
- Catalog
- API / Event / Schema 契约
- CI
- 基础环境
- 基础观测
- 发布回滚
```
##### Phase 2：平台化
增加：
```text
internal-platform/
middle-platform/
```
重点建设：
```text
- Golden path
- 服务模板
- 自助资源申请
- 平台门户
- 数据平台
- API 平台
- 身份平台
- 消息平台
```
##### Phase 3：治理自动化
强化：
```text
- Scorecard
- Policy as Code
- Contract testing
- SLO automation
- Cost attribution
- Security posture management
- Incident review automation
```
---
##### 8. 常见反模式
| 反模式 | 问题 |
| ------------------------- | ----------------------- |
| 把所有公共代码放进 `shared/common` | 很快变成无法治理的垃圾桶 |
| `infra` 里写业务逻辑 | 基础设施和产品边界失控 |
| `middle-platform` 服务某一个产品 | 中台退化成产品后端 |
| 没有 `contracts` | 跨团队协作靠口头约定和代码注释 |
| 没有 `catalog` | 系统多了以后找不到 owner、依赖和生命周期 |
| 没有 `governance` | 目录结构会慢慢腐烂 |
| 只有 Portal，没有平台能力 | 只是入口，不是 IDP |
| 只有文档，没有机器可读契约 | 无法自动校验和治理 |
| 所有团队直接操作底层资源 | 平台无法形成抽象和复用 |
| SLO 只写在 PPT 里 | 不能参与发布、告警和复盘 |
---
##### 9. 推荐判定标准
一个目录是否应该存在，按以下问题判断：
##### 是否进入 `governance/`
```text
它是否定义组织级规则、决策、门禁、风险、SLO、复盘？
```
是，则进入 `governance/`。
##### 是否进入 `contracts/`
```text
它是否是跨团队、跨层、跨系统的机器可读接口？
```
是，则进入 `contracts/`。
##### 是否进入 `catalog/`
```text
它是否描述系统、组件、资源、Owner、生命周期？
```
是，则进入 `catalog/`。
##### 是否进入 `infra/`
```text
它是否负责运行、交付、环境、资源、安全、观测、成本？
```
是，则进入 `infra/`。
##### 是否进入 `internal-platform/`
```text
它是否服务内部开发者，提高开发、交付、运维效率？
```
是，则进入 `internal-platform/`。
##### 是否进入 `middle-platform/`
```text
它是否是多个产品可复用的技术能力，而不是某个产品的业务逻辑？
```
是，则进入 `middle-platform/`。
##### 是否进入 `products/`
```text
它是否直接面向用户、渠道、业务场景或运营场景？
```
是，则进入 `products/`。
##### 是否进入 `shared/`
```text
它是否是无业务语义、低层、稳定、跨域复用的薄能力？
```
是，才进入 `shared/`。
---
##### 10. 最终判断
这个模型的关键不是目录多，而是把企业软件系统中不同类型的“真相”分开：
```text
governance = 规则和演进真相
contracts = 跨层契约真相
catalog = 资产和 owner 真相
infra = 运行底座真相
internal-platform = 开发者体验真相
middle-platform = 可复用技术能力真相
products = 用户价值交付真相
```
所以，较完善的企业级项目架构不应只是“四层架构”，而应是：
```text
governance
+ contracts
+ catalog
+ infra
+ internal-platform
+ middle-platform
+ products
```
再配一个严格受控、极薄的：
```text
shared
```
这是一套更接近现代平台工程、SRE、GitOps、软件资产目录、数据治理和企业级安全治理共识的参考模型。实际落地时可以裁剪，但不建议混淆这些边界。
<a id="reference-engineering-practice-6-full-stack-web-应用结构"></a>
#### 6. Full-Stack Web 应用结构