TypeScript API 版本化：只加了一个可选字段，下游为什么编译挂了

import type { User } from '@acme/api-client'

// 下游用 keyof 驱动表格列配置——完全合法的用法
const columnLabels: Record<keyof User, string> = {
  id: 'ID',
  name: '姓名',
}

// 1) 可选 -> 必填：下游所有构造点立刻缺字段
interface TaskV1 { id: string; title?: string }
interface TaskV2 { id: string; title: string }

// 2) 联合收窄：昨天能传任意 string，今天不能了
type StatusV1 = string
type StatusV2 = 'active' | 'frozen'

// 3) 导出改名：import { Task } 直接红
export { type TaskV2 as Task }

// 4) 字面量 widening：没写显式返回类型的导出函数尤其危险
function envV1() { return 'prod' as const }   // 'prod'
function envV2() { return getEnvName() }      // string，实现一改推断就变
// 下游 const e: 'prod' = env() 在 v2 下编译失败

// 5) keyof / 映射类型的连锁反应：本篇开头的事故
type Labels = Record<keyof User, string>

npm i -D @microsoft/api-extractor
npx api-extractor init     # 生成 api-extractor.json

{
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
  "apiReport": {
    "enabled": true,
    "reportFolder": "<projectFolder>/etc/",
    "reportTempFolder": "<projectFolder>/etc/temp/"
  },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts"
  }
}

# 本地：生成或更新 .api.md，随代码一起提交
npx api-extractor run --local

# CI：不带 --local，.api.md 与产物不一致时直接失败
npx api-extractor run

// 新增可选字段：对绝大多数下游兼容，除了 keyof 映射（见第五类）
export interface Task {
  id: string
  retries?: number          // 新增
}

// 加函数能力：新增重载放前面，旧签名原样保留
export function getTask(id: string): Promise<Task>
export function getTask(ids: string[]): Promise<Task[]>
export function getTask(idOrIds: string | string[]): Promise<Task | Task[]> {
  return typeof idOrIds === 'string'
    ? http.get(`/tasks/${idOrIds}`)
    : Promise.all(idOrIds.map((id) => http.get(`/tasks/${id}`)))
}

type FetchEvent =
  | { type: 'start'; url: string }
  | { type: 'success'; ms: number }

function log(e: FetchEvent) {
  switch (e.type) {
    case 'start': return
    case 'success': return
    default: {
      const _never: never = e   // v2 给联合加 { type: 'abort' } 后这行报错
      return _never
    }
  }
}

export interface Task {
  /** @deprecated 3.4 起改用 retries，弃用窗口两个 minor，v4.0 移除 */
  retryCount?: number
  retries?: number
}

// eslint.config.js —— typescript-eslint v8 起内置 no-deprecated（需要类型信息）
import tseslint from 'typescript-eslint'

export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: { parserOptions: { projectService: true } },
    rules: { '@typescript-eslint/no-deprecated': 'error' },
  },
)

import { z } from 'zod'

export const UserSchema = z.object({
  id: z.string(),
  status: z.enum(['active', 'frozen']),   // 运行时真的只会是这两个值
})
export type User = z.infer<typeof UserSchema>

// 边界处 parse：契约不一致就在门口抛，别让脏数据进类型系统
export async function getUser(id: string): Promise<User> {
  const res = await http.get(`/users/${id}`)
  return UserSchema.parse(res.data)
}

import { expectTypeOf } from 'expect-type'

// 有人把 status 放宽回 string 或收窄成单值，这条测试立刻失败
expectTypeOf<User['status']>().toEqualTypeOf<'active' | 'frozen'>()

// codemods/rename-retryCount.cjs —— jscodeshift 批量迁移下游代码
module.exports = function transformer(file, api) {
  const j = api.jscodeshift
  return j(file.source)
    .find(j.Identifier, { name: 'retryCount' })
    .forEach((p) => j(p).replaceWith(j.identifier('retries')))
    .toSource()
}

npx jscodeshift -t codemods/rename-retryCount.cjs ../admin-console/src

/** @deprecated 改用 listTasks，v4.0 移除 */
export function fetchTasks(...args: Parameters<typeof listTasks>) {
  track('deprecated:fetchTasks')   // 上报内部指标，周报看曲线
  return listTasks(...args)
}

{
  "name": "@acme/api-client",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./v2": {
      "types": "./dist/v2/index.d.ts",
      "default": "./dist/v2/index.js"
    }
  }
}