什么是 fun？
fun 是一个基于 fasthttp 的 单端点 RPC 框架。它把「定义服务 → 暴露接口 → 前后端联调」这条链路压缩到最短：
- 后端只有一个业务端点：
POST /cell，请求体里带serviceName/methodName，框架反射调用对应方法； - 服务就是 Go 结构体，导出方法即 RPC 端点，不需要写路由、不需要手写参数解析；
- 一条命令生成带完整类型的 TypeScript 客户端，前端不再手拼 URL 和 DTO。
go
f := fun.GetFun()
f.BindService(&UserSvc{}) // 注册服务
go f.Start(cfg.ListenPort()) // 启动 HTTP，业务只响应 POST /cell为什么是单端点？
传统 REST 把业务语义分散到 URL、方法、状态码里，前端要为每个接口手写请求代码，后端要为每个路由写参数绑定。fun 的取舍是：
| 传统 REST | fun |
|---|---|
| 每个接口一个路由 | 所有业务走 POST /cell |
| URL + 动词表达语义 | serviceName.methodName 表达语义 |
| 手写 Controller / 路由 | 结构体导出方法自动注册 |
| 前端手写 fetch 封装 | 生成 TS SDK，类型直达 |
| 参数校验散落各处 | DTO 规则集中校验（注册期 + 运行期） |
换来的是：新增一个接口 = 写一个 Go 方法 + 重新生成客户端，仅此而已。
无法塞进 RPC 的场景（GET 直链下载、健康检查、支付异步回调）由 自定义路由 承接；跨域由 CORS 白名单 处理。
核心特性
- 单端点 RPC：
POST /cell，方法签名(error)、(T, error)、(stream, error)、(T, stream, error) - 依赖注入：
fun.Wired[T]()建单例，auto标签字段递归装配，New()初始化连接资源 - Guard 鉴权：全局 + 服务级 + 路由级中间件，返回 error 短路并转统一错误响应
- NDJSON 流式：
*fun.Stream逐行推送，支持首条消息 + 后续流，服务端 25s 心跳保活 - 自定义路由（v1.3.0+）：
BindRoute注册 GET/POST 回调、健康检查、通配符路径 - 请求体上限控制（v1.3.3+）：
SetBodyLimit支持大体积 multipart 上传 - CORS 跨域（v1.3.5+）：
f.CORS(origins...)白名单按需放行，预检 204 直答，覆盖/cell与全部自定义路由 - TypeScript 客户端生成：
BindServiceForGen+GenCode(fun.GenTs{})免基础设施生成，产物带result<T>归一化错误与拦截器
一次请求的生命周期
客户端 fun 服务端
│ POST /cell │
│ {serviceName, methodName, │
│ data, state} │
├───────────────────────────────▶│ ① 解析请求，定位 ServiceName.MethodName
│ │ ② 依次执行 全局 Guard → 服务级 Guard（error 即短路）
│ │ ③ 每请求新建服务实例并注入依赖
│ │ ④ data 解码为 DTO（定宽整型/枚举校验）
│ │ ⑤ 反射调用业务方法
│◀───────────────────────────────┤ ⑥ Result（键递归转小写）或 NDJSON 流
│ {code, msg, status, data} │- 第 ② 步失败：直接返回 Guard 给出的错误（
fun.Error(code, msg)可带业务码）。 - 第 ④ 步失败：返回
status=1的框架错误，细节记服务端日志、不外泄。 - 第 ⑤ 步业务返回
fun.Error(...)：status=2，code/msg 原样透传。 - 流式方法：第 ⑥ 步改为
application/x-ndjson逐行推送，详见流式响应。
版本沿革
| 版本 | 要点 |
|---|---|
| v1.1.0 | BindRoute 自定义 GET/POST 路由（回调、健康检查） |
| v1.3.0 | BindRoute 通配符路由 /prefix/*，RouteCtx.Wildcard 取剩余路径 |
| v1.3.1 | TS 客户端可靠性：所有失败统一归一为 Result 并经过响应拦截器 |
| v1.3.2 | 每请求上下文（request/stream options + state）与免基础设施的生成期注册 BindServiceForGen |
| v1.3.3 | 新增 SetBodyLimit：自定义路由可放宽请求体上限，支持大体积 multipart 上传 |
| v1.3.4 | 错误通道 API（Guard 返回 error 短路）、正确性修复与服务端加固 |
| v1.3.5 | 新增 CORS：来源白名单按需放行，预检 204 直答，覆盖 /cell 与全部自定义路由 |
| v1.3.6 | 流式长连接可靠性：服务端 25s 空行心跳；TS 客户端原生重连（dto 工厂刷新游标 + 指数退避）与空闲看门狗（retry / idleTimeoutMs，默认关闭） |
本文档基于 v1.3.6 源码编写，与仓库 docs/README.zh.md 同步。