应使用映射类型（Mapped Types）显式建模「API路径→响应类型」的精确映射，而非 Record；需先定义字面量联合路径类型，再通过 keyof 和索引访问构建强类型客户端，确保调用时自动推导正确返回类型并拦截非法路径。
为什么直接用 Record<string any></string> 会丢失 API 响应结构信息
很多封装请求函数时图省事，把返回类型写成 Promise<record any>></record>，结果调用方完全不知道接口返回字段名、是否可选、嵌套层级。TypeScript 类型检查形同虚设，运行时才报 Cannot read property 'id' of undefined。
根本问题在于：你没把「接口路径 → 响应类型」的映射关系显式建模。Mapped Types 就是用来干这个的——它能基于一个键集合（比如 API 路径字面量）批量生成对应的响应类型，且保持每个路径绑定唯一、精确的类型。
- 必须先定义所有合法 endpoint 的联合字面量类型，例如：
type ApiPath = '/users' | '/posts/:id' | '/profile' - 不能用字符串拼接或动态 key，否则 TS 无法在编译期推导映射关系
- 路径中的参数占位符（如
:id）要统一替换为泛型参数或提前规范化，否则类型无法对齐
用 Record<k t></k> + 索引访问类型实现路径到响应类型的静态映射
核心不是炫技，而是让 api.get('/users') 的返回值自动推导为 User[]，而不是 any。关键在两步：定义路径-类型映射表，再用 Mapped Type 把它“展开”成对象结构。
示例结构：
interface ApiResponseMap {
'/users': User[];
'/users/:id': User;
'/posts': Post[];
}
type ApiClient = {
[K in keyof ApiResponseMap]: (path: K) => Promise<ApiResponseMap[K]>;
};
这样 client.get('/users') 的返回类型就是 Promise<user></user>，而传入非法路径（如 '/foo'）会直接报错。
-
keyof ApiResponseMap是字面量联合类型，TS 能精确识别每个 key - 不要把
ApiResponseMap定义成Record<string ...></string>，那会擦除 key 的具体值 - 如果后端路径带 query 参数（如
/users?role=admin），类型上仍应以基础路径为准，参数校验交给函数重载或单独的params参数
处理动态路径参数（如 /users/:id）时怎么保留类型安全
直接写 '/users/:id' 会导致调用时传入 api.get('/users/123') 类型不匹配——因为 '/users/123' 不是 '/users/:id' 的子类型。需要把路径参数抽离，用函数签名承载。
使用 Scrapfly SDK（scrapfly-sdk）在 TypeScript 或 JavaScript 中进行网页抓取，用于用户请求抓取 URL、绕过反爬虫防护、渲染页面等场景。
推荐做法：把带参数的路径定义为函数类型，而非字符串字面量：
interface ApiResponseMap {
'/users': User[];
'/users/:id': (id: string) => User;
'/posts': Post[];
}
type ApiClient = {
get<K extends keyof ApiResponseMap>(
path: K
): K extends '/users/:id'
? (id: string) => Promise<User>
: Promise<ApiResponseMap[K]>;
};
更实用的方案是拆成两个方法：get(path) 和 getWithParams(path, params)，后者用泛型约束 params 结构（比如用 Extract<k></k> 触发条件类型分支）。
- 别试图在字符串路径里做正则匹配或运行时解析，TS 类型系统不支持
- 路径参数类型（
id: numbervsid: string）必须和后端实际接收类型一致，否则类型安全失效 - 如果多个路径共享同一参数结构（如都含
:orgId），建议提取为type PathWithOrgId = '/orgs/:orgId/members' | '/orgs/:orgId/settings'，再用条件类型统一处理
为什么 as const 和 typeof 组合比手写字面量更可靠
手写 '/users' 容易漏、难维护。真实项目中，API 路径通常来自配置对象或后端文档生成的 JSON。这时要用 as const 锁定字面量类型，再用 typeof 提取键：
const API_ROUTES = {
USERS: '/users',
USER_DETAIL: '/users/:id',
POSTS: '/posts',
} as const;
type ApiPath = typeof API_ROUTES[keyof typeof API_ROUTES]; // '/users' | '/users/:id' | '/posts'
后续所有映射类型（ApiResponseMap、ApiClient）都基于 ApiPath 构建，路径变更只需改 API_ROUTES，类型自动同步。
- 没有
as const，API_ROUTES的类型是{ USERS: string; ... }，字面量信息就丢了 - 如果路径来自外部 JSON 文件，需用
declare module '*.json'+as const声明，否则无法保证类型精度 - 别在映射类型里写
string或unknown占位，那等于放弃类型安全的起点
最常被忽略的一点：Mapped Types 的类型推导深度有限。嵌套过深（比如三层以上条件类型嵌套）会让编辑器卡顿、报错模糊。遇到这种情况，优先拆分成中间类型别名，而不是硬塞进一个映射表达式里。
