# 下个版本新特性设计

本文档用于整理 `typescript-boot` 下一版本值得优先提供的新能力。

`typescript-boot` 的定位不是“大而全框架”，而是一个让使用者可以快速搭建后端 HTTP 服务的 TypeScript 脚手架。因此，下个版本的新特性应该继续围绕下面几个目标展开：

- 让使用者少写重复代码
- 让接口定义更清晰、更稳定
- 让常见后端能力尽量开箱即用
- 不引入过重的运行时依赖和复杂配置

## 一、建议优先级

建议下一版本按下面的优先级推进：

1. WebSocket 接口服务发布能力
2. 请求参数校验与自动转换能力
3. 数据库事务能力的框架级封装
4. OpenAPI 导出与客户端代码生成
5. 定时任务与后台任务能力

其中前 3 项最符合当前项目定位，也最容易让使用者直接感受到价值。

## 二、特性 1：提供可发布的 WebSocket 接口服务

### 1.1 目标

除了现在的 `publishService(new XxxService())` 这种 HTTP 接口发布方式，还应支持发布一个可与前端进行 WebSocket 通讯的接口服务。

### 1.2 为什么值得做

当前项目已经覆盖了：

- HTTP 接口发布
- 会话与权限
- 数据库
- 日志
- Redis

但对于很多后台系统来说，还会有下面这些实时场景：

- 扫码登录状态推送
- 导入/导出进度推送
- 审批流或任务状态变化通知
- 实时聊天、实时告警、看板刷新

这些能力如果每个使用者都自己接 `ws` 或 `socket.io`，就会偏离“脚手架开箱即用”的定位。

### 1.3 建议设计

建议新增一个和 `BaseService` 平行的 websocket service 基类，例如：

```ts
class BaseSocketService {
}
```

再由 `SeeksWebServer` 提供类似能力：

```ts
server.publishSocketService(new MessageSocketService());
```

建议支持的最小能力：

- 连接建立与断开回调
- 自定义 websocket path
- 鉴权能力
- 向指定用户推送消息
- 向指定房间或频道广播消息
- 统一日志记录

### 1.4 建议的最小版本范围

第一版不要做得太重，建议只实现：

- 基于原生 `ws` 或轻量方案
- 支持 token 鉴权
- 支持按用户 ID 建立连接映射
- 支持服务端主动推送
- 支持基础事件分发

不建议第一版就做：

- 分布式消息同步
- 集群房间管理
- 复杂事件总线

这些能力可以等 Redis 联动版本再补。

## 三、特性 2：请求参数校验与自动类型转换

### 2.1 目标

当前 `typescript-boot` 已经支持：

- `@apiParamFromBody()`
- `@apiParamFromQuery()`
- `@apiParamFromHeader()`
- `@apiBodyAsParam()`

但还缺少“参数是否合法”的框架级约束。下个版本应该提供轻量但统一的参数校验能力。

### 2.2 为什么值得做

现在使用者通常还需要在方法体内手写：

```ts
throwWarningErrorIf(!id, 'id不能为空');
throwWarningErrorIf(pageSize < 1, 'pageSize不正确');
```

这会带来几个问题：

- 参数错误判断分散在业务代码里
- 文档里能看到参数，但看不到更精确的校验规则
- 同样的校验逻辑在很多接口中重复出现

### 2.3 建议设计

建议增加一组轻量注解，而不是直接引入很重的外部校验框架。

例如：

```ts
@apiRequired()
@apiMin(1)
@apiMax(100)
@apiPattern(/^[A-Z0-9_]+$/)
```

也可以增加对象级校验入口，例如：

```ts
@apiValidate()
```

### 2.4 自动转换能力

除了校验，建议同时支持基础自动转换：

- query 中的 `"1"` 转为 `number`
- `"true"` / `"false"` 转为 `boolean`
- 日期字符串按约定转为 `Date` 或保留字符串
- 数组参数支持按逗号或重复 query 参数解析

### 2.5 建议的最小版本范围

第一版建议支持：

- required
- min / max
- minLength / maxLength
- regex
- enum
- number / boolean 基础自动转换

并且校验失败时统一返回：

```json
{
  "code": 456,
  "error": true,
  "message": "参数xxx不合法"
}
```

## 四、特性 3：数据库事务能力的框架级封装

### 4.1 目标

当前项目已经有数据库客户端与批量更新能力，但缺少一个对业务开发足够友好的事务封装。

### 4.2 为什么值得做

对后台项目来说，多表写入是高频操作，例如：

- 创建订单和写订单明细
- 创建用户并初始化角色
- 保存审批记录并更新主单状态

如果没有统一事务封装，使用者就需要：

- 手动拿连接
- 手动开启事务
- 手动提交
- 手动回滚
- 自己处理异常

这与脚手架“降低样板代码”的定位不一致。

### 4.3 建议设计

建议提供两种方式，至少先实现其中一种：

方式一：编程式事务

```ts
await dbClient.withTransaction(async (tx) => {
  await tx.update(...);
  await tx.update(...);
});
```

方式二：装饰器事务

```ts
@dbTransaction()
async createOrder(...) {
}
```

### 4.4 建议的最小版本范围

第一版建议优先做编程式事务，因为：

- 实现更稳定
- 更容易适配不同数据库实现
- 出错路径更清晰

建议支持：

- 自动 commit / rollback
- 在事务上下文中复用同一个连接
- 嵌套事务时至少有明确限制或明确定义

## 五、特性 4：OpenAPI 导出与客户端代码生成

### 5.1 目标

当前项目已经有自己的在线接口文档能力。下一步很自然的方向，是把已有的注解元数据导出为标准 OpenAPI 文档。

### 5.2 为什么值得做

这项特性会直接放大当前文档系统的价值：

- 前端可以直接生成类型安全的请求代码
- 测试工具可以直接导入接口定义
- 第三方平台更容易对接
- 使用者不需要额外维护一套 Swagger 描述

### 5.3 建议设计

建议提供：

- `/typescript-boot/openapi.json`
- 一个命令行工具，用于基于 openapi 生成 TS 客户端

如果完整 OpenAPI 成本较高，也可以先提供：

- 当前内部文档 JSON 的稳定导出格式
- 官方的 TS 客户端生成脚本

### 5.4 建议的最小版本范围

第一版建议先支持：

- path
- method
- query/body/header 参数
- 返回值类型
- 权限说明

先不追求把所有复杂对象描述到完全标准化。

## 六、特性 5：定时任务与后台任务能力

### 6.1 目标

为使用者提供简单的定时任务注册能力，以及后续可扩展的后台任务能力。

### 6.2 为什么值得做

一个后端脚手架除了“接口服务”，通常还会承载：

- 定时同步
- 过期数据清理
- 定时统计
- 消息补偿

如果这些任务完全让用户自己拼装 `node-cron`、日志、异常处理、单机锁，就会丢掉框架一致性。

### 6.3 建议设计

建议后续提供：

```ts
server.publishJob(new DemoJobService());
```

或者：

```ts
@scheduled('0 */5 * * * *')
async syncData() {}
```

### 6.4 建议的最小版本范围

第一版只做：

- 单机定时任务
- 启停日志
- 异常日志
- 可选的 Redis 分布式锁，防止多实例重复执行

不建议第一版就做复杂任务编排。

## 七、我认为最适合 `typescript-boot` 的其他候选能力

如果下个版本资源允许，下面这些能力也值得考虑，但优先级略低于前面 5 项：

### 7.1 接口级限流与幂等

适合支付、创建订单、短信发送、验证码发送等场景。

建议能力：

- `@apiRateLimit()`
- `@apiIdempotent()`

### 7.2 统一缓存注解

项目已经有 Redis 能力，但缺少框架级缓存封装。

建议能力：

- `@apiCache(ttl)`
- 支持按参数生成 cache key
- 支持手动失效

### 7.3 文件上传下载能力增强

当前已有上传工具和 Buffer 下载能力，但还可以继续增强：

- 上传文件类型校验
- 单文件大小限制注解
- OSS/MinIO 抽象
- 图片缩略图或元信息获取

## 八、最终建议

如果只做一版真正有感知的升级，我建议按下面顺序落地：

1. WebSocket 接口服务发布能力
2. 请求参数校验与自动转换
3. 数据库事务能力封装

原因很简单：

- 这三项与当前项目能力最连续
- 对使用者的收益最直接
- 不会把框架做得过重
- 能明显提升“脚手架开箱即用”的完成度

如果还有额外时间，再继续做：

4. OpenAPI 导出
5. 定时任务能力

这会让 `typescript-boot` 从“能快速写接口”进一步升级为“能快速完成一个中小型后端系统的核心骨架”。