NSwag TypeScript客户端为何使用`null as any`断言？

问题场景 #

NSwag生成的TypeScript客户端代码示例：

protected processGetById(response: Response): Promise<Thing> {
    const status = response.status
    let _headers: any = {}
    if (response.headers && response.headers.forEach) {
      response.headers.forEach((v: any, k: any) => (_headers[k] = v))
    }
    if (status === 200) {
      return response.text().then((_responseText) => {
        let result200: any = null
        let resultData200 =
          _responseText === ''
            ? null
            : JSON.parse(_responseText, this.jsonParseReviver)
        result200 = Thing.fromJS(resultData200)
        return result200
      })
    } else if (status !== 200 && status !== 204) {
      return response.text().then((_responseText) => {
        return throwException(
          'An unexpected server error occurred.',
          status,
          _responseText,
          _headers
        )
      })
    }
    return Promise.resolve<Thing>(null as any)
  }

这段代码的返回类型标注为Promise<Thing>，但实际会在204状态下返回null，且通过null as any绕过类型检查，导致类型标注与实际行为不符。

1. null as any是否违背TypeScript的设计初衷？ #

是的。TypeScript的核心目标是通过静态类型检查建立可靠的类型契约，提前拦截类型不匹配的潜在错误。这里用null as any强行将null断言为Thing类型，直接绕过了TS的类型校验机制，破坏了类型系统的可信度——开发者无法依赖类型标注判断实际可能的返回值，相当于让类型系统失去了原本的作用，完全违背了TS的设计初衷。

2. 为什么默认不将返回类型定义为Promise<Thing | null>？ #

这是NSwag模板的设计选择，主要有以下可能的原因：

• 历史兼容考量：早期TypeScript对联合类型的支持不够成熟，模板设计时可能优先保证旧版本兼容性，没有采用更精确的联合类型标注。
• API场景的默认假设：模板默认假设成功响应（200）必然返回有效数据，而204这类无内容的响应被视为边缘场景，未纳入默认的类型标注逻辑。
• 通用性与简洁性权衡：NSwag需要适配各类API场景，默认模板可能优先保证多数场景的代码简洁性，把边缘场景的精确类型处理交给开发者自定义调整（比如修改模板、手动补充类型）。

解决建议 #

如果要修复这种类型不一致的问题，可以采取以下方案：

• 自定义NSwag模板：修改生成模板中的返回类型定义为Promise<Thing | null>，同时移除null as any的断言，让类型标注与实际行为一致。
• 调用时手动处理：在调用该方法时，通过类型守卫显式处理null情况：

const thing = await api.getById(1);
if (thing === null) {
  // 处理无内容的逻辑
} else {
  // 处理Thing类型的业务逻辑
}

内容的提问来源于stack exchange，提问作者cyclingLinguist