gin
1c3f8b39a3
Co-authored-by: gin <gin-18@qq.com> Co-authored-by: gin <dengxinmin@owlscm.com> Reviewed-on: #1
134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
# 后端业务功能开发规范
|
||
|
||
本文是本项目 Hono 后端新增或修改业务功能时的权威规范。后端代码位于 `backend`，基于 Hono、Prisma、Redis 和统一响应/错误协议实现。
|
||
|
||
## 架构原则
|
||
|
||
后端业务代码按 `Route -> Feature Service -> Prisma/Redis/shared Service` 组织。
|
||
|
||
优先参考这些现有模块：
|
||
|
||
- `backend/src/routes/modules/system-user.ts`
|
||
- `backend/src/routes/modules/system-role.ts`
|
||
- `backend/src/routes/modules/system-menu.ts`
|
||
- `backend/src/routes/modules/system-notice.ts`
|
||
- `backend/src/features/system/system.service.ts`
|
||
- `backend/src/features/collaboration/collaboration.service.ts`
|
||
|
||
Route 只负责 HTTP 层编排，不直接堆业务规则。复杂查询或业务流程放到 `features/<domain>` 下的 service 中。不要把 Prisma 原始记录直接作为跨模块业务契约扩散，面向前端的响应应在 service 中整理为稳定 DTO 形态。
|
||
|
||
## 开发准备
|
||
|
||
开发新后端业务功能前，应先确认需求所属领域、涉及的数据表、接口范围、权限标识和相似模块。
|
||
|
||
开始编码前必须先做一次相似模块调研，确认目标功能最接近 `user`、`role`、`menu`、`notice`、`config`、`collaboration` 还是其他模块，再按相似模块的命名、路由、分页、异常、权限、导出和测试风格实现。
|
||
|
||
## 目录结构
|
||
|
||
路由入口放在：
|
||
|
||
```text
|
||
backend/src/routes/modules/<module>.ts
|
||
```
|
||
|
||
业务代码放在：
|
||
|
||
```text
|
||
backend/src/features/<domain>/
|
||
├── <domain>.service.ts
|
||
├── <domain>.schemas.ts
|
||
└── public-config.ts
|
||
```
|
||
|
||
共享能力放在：
|
||
|
||
```text
|
||
backend/src/shared/
|
||
├── auth/
|
||
├── cache/
|
||
├── config/
|
||
├── db/
|
||
├── hono/
|
||
└── http/
|
||
```
|
||
|
||
数据库 schema 维护在：
|
||
|
||
```text
|
||
backend/prisma/schema.prisma
|
||
```
|
||
|
||
初始化 SQL 维护在：
|
||
|
||
```text
|
||
backend/sql/init.sql
|
||
```
|
||
|
||
## 各层职责
|
||
|
||
Route 负责 HTTP 层：
|
||
|
||
- 声明 Hono 路由和 HTTP 方法。
|
||
- 使用 `requireAuth`、`requirePermission` 做认证和权限控制。
|
||
- 使用 `zValidator` 校验请求体或查询参数。
|
||
- 调用 Feature Service。
|
||
- 使用 `ok()`、`page()` 或下载响应工具返回统一响应。
|
||
|
||
Feature Service 负责编排业务用例：
|
||
|
||
- 分页查询、详情查询、导出查询、新增、修改、删除。
|
||
- 处理业务校验和状态变化。
|
||
- 调用 Prisma、Redis 或 shared service 完成持久化和缓存操作。
|
||
- 将数据库记录转换为前端响应对象。
|
||
- 业务失败时抛出 `ApiError`，不要返回布尔值让 Route 解释。
|
||
|
||
Shared 层只放跨模块复用能力：
|
||
|
||
- 认证、权限、会话和当前用户。
|
||
- Prisma 和 Redis 客户端。
|
||
- 统一响应、错误处理、下载、Excel。
|
||
- 菜单、配置等跨模块辅助逻辑。
|
||
|
||
## 开发流程
|
||
|
||
1. 检索并阅读一个最相似的 Hono 模块，确认命名、路由、分页、异常、权限和导出风格。
|
||
2. 确认数据库表结构，必要时更新 `prisma/schema.prisma` 和初始化 SQL。
|
||
3. 在 `features/<domain>` 中实现业务函数，保持函数职责单一。
|
||
4. 在 `routes/modules/<module>.ts` 中添加路由，接入认证、权限、校验和统一响应。
|
||
5. 如功能出现在后台菜单，补充权限标识和 `backend/sql/init.sql` 菜单数据。
|
||
6. 如需要字典数据，优先使用 `features/system/system-dictionary.ts` 中的枚举式配置，不要默认创建字典管理表。
|
||
7. 增加聚焦测试或至少运行 TypeScript 检查；高风险改动应补充接口级验证。
|
||
8. 运行 `pnpm --dir backend typecheck`。
|
||
|
||
## 权限、日志和错误
|
||
|
||
权限码必须和前端菜单或按钮权限保持一致，格式参考现有系统功能：
|
||
|
||
```ts
|
||
requirePermission("system:user:list")
|
||
```
|
||
|
||
业务错误使用 `ApiError` 和 `ErrorCodes`：
|
||
|
||
```ts
|
||
throw new ApiError(ErrorCodes.failed, "操作失败");
|
||
```
|
||
|
||
接口返回使用统一响应：
|
||
|
||
```ts
|
||
return c.json(ok(result));
|
||
return c.json(page(result.records, result.total));
|
||
```
|
||
|
||
导出接口优先使用 `createWorkbookResponse()`。
|
||
|
||
## 验收清单
|
||
|
||
- Route 只有 HTTP 编排逻辑。
|
||
- 业务校验位于 Feature Service，不散落在前端或 Route。
|
||
- 查询返回稳定 DTO，分页返回统一 `page()` 响应。
|
||
- 写请求使用 zod schema 校验。
|
||
- 权限码、菜单 SQL、前端 API 调用保持一致。
|
||
- `pnpm --dir backend typecheck` 通过。
|