TypeScript satisfies 在泛型返回值中如何保留字面量

我在把一组前端路由配置交给泛型工厂时，最容易踩的坑不是约束写错，而是返回值被推断得太宽：本来希望 kind 是 "list"，结果下游只看到了 string。解决思路是把职责拆开：satisfies 负责检查对象是否符合约束，泛型函数负责接住调用方的具体类型；如果还要保留每个字符串和数字的精确字面量，再组合 as const。

要让字面量进入泛型返回值，先用 satisfies 校验对象，再让函数以 T 返回它；需要保留精确值时使用 as const satisfies Constraint。不要用接口类型注解替代这条链路，因为注解会把表达式视为约束类型。

先把约束、推断和返回值分开

下面这个约束只描述路由必须具备什么：kind 只能是两个分支，path 必须以斜杠开头。这里不把对象声明成 RouteConfig，因为那样得到的变量类型就是接口本身，具体属性可能被统一成联合类型。

type RouteKind = "list" | "detail";

interface RouteConfig {
  kind: RouteKind;
  path: `/${string}`;
}

function defineRoute(value: T): T {
  // 泛型返回 T，保留调用方传入对象的具体结构。
  return value;
}

const route = defineRoute({
  kind: "list",
  path: "/users",
} satisfies RouteConfig);

// route.kind 可按具体对象继续参与类型推断。
type RouteKindFromReturn = typeof route.kind;

satisfies RouteConfig 会检查缺少 kind、路径格式不符或多出不允许字段等问题，但它的目标不是把结果声明成 RouteConfig。真正决定返回值形状的是泛型参数 T。这正是“约束”和“推断”可以同时存在的地方。

用 satisfies 把对象边界交给泛型函数

实际项目里通常会把配置先命名，再交给工厂函数。命名的好处是可以单独复用对象，也能让错误位置更容易阅读。重点是不要写成 const routeInput: RouteConfig，而是让表达式通过 satisfies 接受校验。

const routeInput = {
  kind: "detail",
  path: "/users/:id",
  cache: "short",
} as const satisfies RouteConfig;

const detailRoute = defineRoute(routeInput);
type DetailRoute = typeof detailRoute;

// 这里的赋值要求 kind 仍然是 detail，而不是任意 string。
const onlyDetail: "detail" = detailRoute.kind;

// 这个错误用例用于检查约束，不是运行时校验。
// const badRoute = { kind: "list", path: "users" } satisfies RouteConfig;

这个例子同时用了两个运算符，但职责不同：as const 让属性值尽量保持字面量并加上 readonly；satisfies RouteConfig 负责检查它仍然符合路由协议；defineRoute 则以 T 原样返回。少掉其中一个，结果都会不同。

需要精确字面量时，重点检查 readonly 影响

如果只写 satisfies，它保证的是表达式类型不会被目标类型替换，并不承诺每个属性值都永远是最窄的字面量。对象属性、数组元素和函数参数的推断仍受上下文影响。要把 "detail"、"/users/:id" 这类值作为类型的一部分保存下来，可以使用 as const satisfies。

迁移时我会先问一个问题：这个对象是“只读配置”还是“后续要编辑的数据”。前者可以直接组合 as const；后者更适合只用 satisfies，或在泛型约束中精确描述需要的字段，避免把只读性传给整个返回对象。

迁移检查清单与常见问题

1. 先写约束类型，只放确实需要检查的字段，不要把所有业务字段都塞进一个接口。
2. 让泛型函数使用 T extends Constraint 并返回 T，否则检查通过也可能在函数出口丢掉具体类型。
3. 对常量配置使用 as const satisfies，然后用 typeof result 或字面量赋值做静态验证。
4. 对可变对象检查 readonly 是否符合预期；它不会在 JavaScript 运行时冻结对象。
5. 不要把 satisfies 当成 API 入参校验器，外部 JSON 仍需在运行时解析和校验。

常见问题

satisfies 会把字符串自动变成最窄的字面量吗？

不一定。它主要保证表达式满足约束并保留表达式类型；如果业务要求精确值参与后续类型判断，优先使用 as const satisfies，再检查由泛型函数返回的类型。

为什么泛型函数不能返回 RouteConfig？

返回 RouteConfig 会主动把调用方的具体对象收窄到接口视角。改成返回 T，并让 T extends RouteConfig 承担约束，才能保留调用方信息。

as const satisfies 能替代运行时校验吗？

不能。两者都属于 TypeScript 编译期类型操作，生成 JavaScript 后不会检查服务器返回的 JSON，也不会自动冻结对象。