wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-01 Common Architecture Foundation #1

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端统一的架构规范层（Common Layer），为所有业务模块提供一致的编码标准、错误处理、分页、响应格式、权限校验和日志规范。

实施状态 — ✅ 全部完成

模块 文件 说明
统一响应格式 src/common/interceptors/response.interceptor.ts { success, data, timestamp } 全局包装
全局异常处理 src/common/filters/global-exception.filter.ts { success: false, statusCode, message }
TraceId 全链路透传 src/common/interceptors/trace-id.interceptor.ts x-trace-id 请求头自动生成/透传
C端 JWT Guard src/common/guards/jwt-auth.guard.ts Bearer Token 校验
Admin JWT Guard src/common/guards/admin-auth.guard.ts Admin Token + refresh 队列
Admin RBAC Guard src/common/guards/admin-roles.guard.ts @AdminRoles('SUPER_ADMIN') 角色层级
可选认证 Guard src/common/guards/optional-auth.guard.ts 未登录也可访问
@AdminPublic() src/common/decorators/admin-public.decorator.ts 标记白名单接口
@CurrentUser() src/common/decorators/current-user.decorator.ts 注入当前用户
DTO 校验 src/common/pipes/strict-validation.pipe.ts class-validator + whitelist
分页 DTO src/common/dto/pagination.dto.ts { page, limit }
Helmet main.ts 全局安全头
CORS main.ts 生产白名单
Trust Proxy main.ts app.set('trust proxy', 1)
限流 src/common/decorators/rate-limit.decorator.ts @AdminLoginRateLimit()
Admin 角色体系 src/common/types/admin-role.enum.ts SUPER_ADMIN > ADMIN > ...
Swagger main.ts 15+ tag 分组 + Basic Auth
BaseQueryService src/common/services/base-query.service.ts 读操作抽象基类
BaseCommandService src/common/services/base-command.service.ts 写操作抽象基类
BaseDomainEvent src/common/events/base-domain.event.ts 领域事件基类（eventId/occurredAt/eventType）
敏感日志脱敏 src/infrastructure/logger/sensitive-logger.ts maskSensitive() + safeLog()

交付检查

  • 统一响应格式 — ResponseTransformInterceptor
  • 统一错误处理 — GlobalExceptionFilter
  • JWT Guard（C 端 + Admin）— jwt-auth.guard + admin-auth.guard
  • Admin RBAC Guard — admin-roles.guard + @AdminRoles
  • Optional Auth Guard — optional-auth.guard
  • @Public / @AdminPublic 装饰器
  • DTO 校验 Pipe — StrictValidationPipe
  • 分页 DTO — PaginationDto
  • @CurrentUser 装饰器
  • Swagger 分组 + Basic Auth 保护
  • Helmet + CORS + Trust Proxy
  • Admin 角色体系
  • 限流基础（Admin Login Rate Limit）
  • TraceId 全链路透传 — TraceIdInterceptor
  • BaseQueryService / BaseCommandService 抽象基类
  • BaseDomainEvent 领域事件基类
  • 结构化日志脱敏 — SensitiveLogger

CAPI/AAPI/IAPI Swagger 分组通过现有 15+ tag 已实现分组，无需额外命名。
i18n 错误信息国际化已预留字段，翻译工作延后到业务稳定后。

## 目标 设计知习后端统一的架构规范层（Common Layer），为所有业务模块提供一致的编码标准、错误处理、分页、响应格式、权限校验和日志规范。 --- ## 实施状态 — ✅ 全部完成 | 模块 | 文件 | 说明 | |------|------|------| | 统一响应格式 | `src/common/interceptors/response.interceptor.ts` | `{ success, data, timestamp }` 全局包装 | | 全局异常处理 | `src/common/filters/global-exception.filter.ts` | `{ success: false, statusCode, message }` | | TraceId 全链路透传 | `src/common/interceptors/trace-id.interceptor.ts` | `x-trace-id` 请求头自动生成/透传 | | C端 JWT Guard | `src/common/guards/jwt-auth.guard.ts` | Bearer Token 校验 | | Admin JWT Guard | `src/common/guards/admin-auth.guard.ts` | Admin Token + refresh 队列 | | Admin RBAC Guard | `src/common/guards/admin-roles.guard.ts` | `@AdminRoles('SUPER_ADMIN')` 角色层级 | | 可选认证 Guard | `src/common/guards/optional-auth.guard.ts` | 未登录也可访问 | | @AdminPublic() | `src/common/decorators/admin-public.decorator.ts` | 标记白名单接口 | | @CurrentUser() | `src/common/decorators/current-user.decorator.ts` | 注入当前用户 | | DTO 校验 | `src/common/pipes/strict-validation.pipe.ts` | class-validator + whitelist | | 分页 DTO | `src/common/dto/pagination.dto.ts` | `{ page, limit }` | | Helmet | `main.ts` | 全局安全头 | | CORS | `main.ts` | 生产白名单 | | Trust Proxy | `main.ts` | `app.set('trust proxy', 1)` | | 限流 | `src/common/decorators/rate-limit.decorator.ts` | `@AdminLoginRateLimit()` | | Admin 角色体系 | `src/common/types/admin-role.enum.ts` | SUPER_ADMIN > ADMIN > ... | | Swagger | `main.ts` | 15+ tag 分组 + Basic Auth | | BaseQueryService | `src/common/services/base-query.service.ts` | 读操作抽象基类 | | BaseCommandService | `src/common/services/base-command.service.ts` | 写操作抽象基类 | | BaseDomainEvent | `src/common/events/base-domain.event.ts` | 领域事件基类（eventId/occurredAt/eventType） | | 敏感日志脱敏 | `src/infrastructure/logger/sensitive-logger.ts` | `maskSensitive()` + `safeLog()` | --- ## 交付检查 - [x] 统一响应格式 — ResponseTransformInterceptor - [x] 统一错误处理 — GlobalExceptionFilter - [x] JWT Guard（C 端 + Admin）— jwt-auth.guard + admin-auth.guard - [x] Admin RBAC Guard — admin-roles.guard + @AdminRoles - [x] Optional Auth Guard — optional-auth.guard - [x] @Public / @AdminPublic 装饰器 - [x] DTO 校验 Pipe — StrictValidationPipe - [x] 分页 DTO — PaginationDto - [x] @CurrentUser 装饰器 - [x] Swagger 分组 + Basic Auth 保护 - [x] Helmet + CORS + Trust Proxy - [x] Admin 角色体系 - [x] 限流基础（Admin Login Rate Limit） - [x] TraceId 全链路透传 — TraceIdInterceptor - [x] BaseQueryService / BaseCommandService 抽象基类 - [x] BaseDomainEvent 领域事件基类 - [x] 结构化日志脱敏 — SensitiveLogger > CAPI/AAPI/IAPI Swagger 分组通过现有 15+ tag 已实现分组，无需额外命名。 > i18n 错误信息国际化已预留字段，翻译工作延后到业务稳定后。
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#1
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?