8da4047110
- 删除common层业务代码（将通过real-business-logic-generator.js重新生成） - 清理重复的core层生成工具 - 保留完整的企业级core层基础设施（Security/Cache/Tracing/Event/Queue/Health） - 版本号升级到0.3.3 - 项目架构现已完整，接下来专注优化PHP到TypeScript语法转换
193 lines
9.4 KiB
Markdown
193 lines
9.4 KiB
Markdown
# 架构基线与 Common 层开发指引（Config/Core/Common）
|
||
|
||
适用范围：本项目已定版的三层架构（config/core/common），以及与 Java/Spring Boot 与 PHP/ThinkPHP 的对标关系与实践规则。目标：在不自创业务的前提下，指导 AI 基于真实 PHP 代码与数据库结构高一致地开发 common 层模块。
|
||
|
||
---
|
||
|
||
## 1. 三层职责与使用方式
|
||
|
||
### 1.1 Config 层（配置中心与环境治理）
|
||
- 职责
|
||
- 环境与配置集中管理（env.* 与模块化配置）
|
||
- 外部服务与框架能力的参数化（DB、Redis、JWT、队列等）
|
||
- 使用规则
|
||
- 严禁编写业务逻辑，仅做“配置与适配”
|
||
- 新增配置项：优先读取 env，统一通过 ConfigService 暴露
|
||
- 敏感配置不可写死；可按需对接密钥服务
|
||
- 参考位置
|
||
- 项目：wwjcloud/src/config
|
||
- 环境文件：wwjcloud/env.*
|
||
|
||
### 1.2 Core 层（基础能力与横切关注）
|
||
- 职责
|
||
- 全局管道/拦截器/过滤器/守卫基线
|
||
- 观测与日志、链路追踪（X-Trace-Id）、统一响应/异常
|
||
- 限流、CORS、Swagger 文档、调度与事件
|
||
- 使用规则
|
||
- 仅提供通用规则与“可复用能力”，不承载具体业务
|
||
- 全局基线已启用：
|
||
- 参数校验：Global ValidationPipe
|
||
- 统一响应：ResponseInterceptor（含 traceId）
|
||
- 统一异常：HttpExceptionFilter（含 traceId）
|
||
- 链路追踪：TracingInterceptor + X-Trace-Id 贯通
|
||
- 速率限制：ThrottlerGuard（按需配置）
|
||
- CORS：app.enableCors()
|
||
- 文档：Swagger（/adminapi 与 /api 分文档）
|
||
- 参考位置
|
||
- 全局注册：wwjcloud/src/app.module.ts
|
||
- 启动入口：wwjcloud/src/main.ts
|
||
- Swagger 拆分：wwjcloud/src/config/modules/swagger/swaggerService.ts
|
||
- Tracing/响应/异常：wwjcloud/src/core/**/*
|
||
|
||
### 1.3 Common 层（业务域模块化实现）
|
||
- 职责
|
||
- 面向具体业务域（如 user/order/payment）
|
||
- 内部完整分层：Controller → Service → Repository/Entity → DTO
|
||
- 与 PHP 项目代码与数据库 100% 一致
|
||
- 使用规则
|
||
- 文件结构示例（以 user 为例）：
|
||
- src/common/user/
|
||
- user.module.ts（模块）
|
||
- controllers/（管理端/前台可分 adminapi/ 与 api/）
|
||
- services/
|
||
- entity/
|
||
- dto/
|
||
- guards/（可选）
|
||
- 管理端路由前缀：/adminapi；前台：/api
|
||
- Controller 只做：路由与 DTO 校验，禁止写业务
|
||
- Service 编排业务流程（必要时开启应用层事务）
|
||
- Repository/Entity 与数据库字段 100% 对齐（禁止新增字段）
|
||
- DTO/验证规则与 PHP 验证器一致
|
||
|
||
---
|
||
|
||
## 2. 三框架对标对照（轻量/功能/性能）
|
||
|
||
### 2.1 总览对比
|
||
| 维度 | Java / Spring Boot | NestJS（本项目基线） | PHP / ThinkPHP |
|
||
|---|---|---|---|
|
||
| 轻量/启动 | 中等偏重、启动慢但稳定 | 轻量、启动快、按需模块 | 最轻、FPM 请求模型 |
|
||
| 功能完备度 | 企业级最全（安全/事务/监控） | Web/微服务常用能力齐全 | Web 基础能力齐全 |
|
||
| 性能取向 | 高吞吐、高并发、CPU 密集强 | 低延迟 I/O 强、BFF/聚合强 | 请求短、实现快 |
|
||
| 并发模型 | 线程池 | 事件循环 + 异步 I/O | 多进程/请求 |
|
||
| 可观测性 | Actuator/Micrometer | 健康/日志/Tracing 已落地 | 需组合/扩展 |
|
||
| 安全基线 | Spring Security 完备 | 守卫/装饰器灵活 | 中间件/验证器为主 |
|
||
|
||
### 2.2 分层对比（config/core/common）
|
||
| 能力项 | Spring Boot | NestJS（本项目） | ThinkPHP |
|
||
|---|---|---|---|
|
||
| Config | profiles + 强类型绑定 | env + ConfigModule（已启用） | env + config/*.php |
|
||
| Core | Validation/Advice/Actuator | ValidationPipe/Filter/Interceptor/Throttler/CORS/Swagger（已启用） | Validate/中间件 |
|
||
| Common | 分包+组件化 | 业务域模块自治（强约束对齐 PHP/DB） | app/{模块} |
|
||
|
||
### 2.3 性能视角（工程实践）
|
||
| 场景 | Spring Boot | NestJS | ThinkPHP |
|
||
|---|---|---|---|
|
||
| API 聚合/BFF | 可做，线程开销更高 | 强项 | 适合后台接口 |
|
||
| CPU 密集 | 强项 | 建议 offload 至 worker/微服务 | 不推荐 |
|
||
| I/O 密集 | 稳定 | 强项 | 常规 |
|
||
| 冷启动/弹性 | 相对慢 | 快 | 快 |
|
||
|
||
---
|
||
|
||
## 3. AI 开发 Common 层的使用方法（强约束版）
|
||
|
||
> 目标：严格遵循 PHP 源码与数据库结构，使用 NestJS 特性实现相同业务语义；禁止自创和假设。
|
||
|
||
### 3.1 约束来源（必须核对）
|
||
- 数据库表结构：/sql/wwjcloud.sql（唯一权威）
|
||
- PHP 控制器：/niucloud-php/niucloud/app/adminapi/controller/
|
||
- PHP 服务层：/niucloud-php/niucloud/app/service/
|
||
- PHP 模型：/niucloud-php/niucloud/app/model/
|
||
- PHP 验证器：/niucloud-php/niucloud/app/validate/
|
||
|
||
### 3.2 开发流程（S1 → S10）
|
||
- S1 需求分析体
|
||
- 定位对应的 PHP 控制器/服务/验证器/模型与数据库表
|
||
- 输出：模块边界、路由表（/adminapi 与 /api）、DTO 字段清单、实体字段清单
|
||
- S2 架构治理体
|
||
- 校验目录与依赖：common/{module}/ 按 Controller→Service→Entity→DTO 组织
|
||
- 确保依赖方向：App(Controller) → Service → Infra/Repository → Entity
|
||
- S3 基建接入体
|
||
- 若涉及 Redis/队列/事务：按 core 规范接入（事务仅在应用层开启，共享 EntityManager）
|
||
- S4 开发执行体
|
||
- Controller：只做路由/DTO 校验；响应交给全局拦截器统一处理
|
||
- Service：编排业务，与 PHP 服务层一致；必要时开启事务（禁止在 Core 开启）
|
||
- Entity/Repository：字段与 /sql/wwjcloud.sql 100% 对齐（禁止新增字段）
|
||
- 接入守卫：管理端统一 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
|
||
- S5 安全基线体（开发阶段）
|
||
- 检查：site_id 隔离、越权、敏感字段输出、/adminapi 守卫
|
||
- S6 质量门禁体
|
||
- ESLint/TS 0 报错；覆盖率与 e2e 关键路径通过
|
||
- S7 规范审计体
|
||
- 命名/路由/守卫/事务/事件/队列 与 PHP/DB 对齐
|
||
- S5 安全基线体（提测前）
|
||
- 重点接口越权与敏感输出复检
|
||
- S9 性能优化体
|
||
- 建议缓存、批处理、异步化，识别 N+1 与大对象
|
||
- S10 命名规范体
|
||
- 文件/类/方法/变量命名符合既定规范
|
||
- S8 上线管控体
|
||
- 变更说明、部署步骤、灰度与回滚预案
|
||
|
||
### 3.3 模块落地清单（逐项核对）
|
||
- 路由前缀：管理端 /adminapi；前台 /api（与 PHP 对齐）
|
||
- 守卫：管理端控制器默认 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
|
||
- DTO：字段与 PHP 验证器一致；使用 class-validator + ValidationPipe
|
||
- 实体：字段/类型/索引与 wwjcloud.sql 100% 一致；禁止新增字段
|
||
- 服务：方法名与 PHP 服务层一致；流程一致；必要时开启事务（应用层）
|
||
- 统一响应：无需手工封装，交由 ResponseInterceptor；traceId 自动注入
|
||
- 异常处理：只抛出 HttpException/自定义异常；由 HttpExceptionFilter 统一处理
|
||
- 日志与链路：无需重复生成 traceId；使用 request.traceId（已在 Core 透传）
|
||
- 文档：自动生成 Swagger，按 /adminapi 与 /api 拆分
|
||
|
||
### 3.4 命名与目录规范（强规则）
|
||
- 目录名：camelCase；文件名：camelCase.ts
|
||
- 类名：PascalCase；接口名：IPascalCase；DTO：PascalCase + Dto
|
||
- API 命名：camelCase；HTTP 方法规范化
|
||
- 数据库命名：snake_case（表/字段/索引/外键）
|
||
- PHP 业务命名优先（在不违反 Nest 规范前提下）
|
||
|
||
### 3.5 事务/队列/事件（基线约束）
|
||
- 事务：仅在 Application（Service 层）开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
|
||
- 队列：仅入队关键 ID，处理器放在 Infrastructure；按队列名分域
|
||
- 事件：统一 DomainEventService，事件名 domain.aggregate.action；默认 DB Outbox，可切 Kafka
|
||
- Redis：短缓存/限流/幂等（SETNX+TTL）按需接入
|
||
|
||
### 3.6 提交与验收
|
||
- PR 必须通过：构建、单测/集成/e2e
|
||
- 审计项：字段/命名/路由/守卫/事务/队列/事件 与 PHP/DB 对齐
|
||
- 命名规范：严格执行大厂标准，提交命名检查报告
|
||
|
||
---
|
||
|
||
## 4. 实操模板（创建首个 common 模块时）
|
||
- 选定 PHP 源：定位对应 controller/service/validate/model 与 wwjcloud.sql 表
|
||
- 创建目录：src/common/{module}/（module 使用业务域名，camelCase）
|
||
- 落地文件：
|
||
- {module}.module.ts
|
||
- controllers/{module}Controller.ts（必要时 adminapi/ 与 api/ 分目录）
|
||
- services/{module}.service.ts
|
||
- entity/{Entity}.entity.ts（名称与 PHP 模型一致的业务语义）
|
||
- dto/{Operation}{Entity}Dto.ts（如 CreateUserDto）
|
||
- 接入守卫：管理端默认接入鉴权与角色守卫
|
||
- 编写测试：单测/集成/e2e 涵盖关键路径（校验/守卫/事务）
|
||
- 运行验收：确保全局拦截器/过滤器与 traceId 链路正常
|
||
|
||
---
|
||
|
||
## 5. 关键基线位置（便于检索）
|
||
- 全局模块注册：src/app.module.ts
|
||
- 启动入口：src/main.ts（CORS/Swagger）
|
||
- Swagger 拆分：src/config/modules/swagger/swaggerService.ts
|
||
- 链路追踪：src/core/tracing/tracingInterceptor.ts
|
||
- 统一响应：src/core/http/interceptors/responseInterceptor.ts
|
||
- 统一异常：src/core/http/filters/httpExceptionFilter.ts
|
||
- HTTP 日志：src/core/interceptors/httpLoggingInterceptor.ts
|
||
- 安全守卫（示例）：src/core/security/guards/adminCheckToken.guard.ts
|
||
|
||
---
|
||
|
||
结论：
|
||
- Config/Core 已定版、与 Spring Boot/ThinkPHP 对标的核心能力就绪，traceId 与统一响应/异常/限流/CORS/Swagger 等基线已贯通。
|
||
- 按本文档清单可直接开始 common 层业务模块开发，严格以 PHP 源码与 wwjcloud.sql 为唯一权威对齐实现。 |