LANG-05 · PROGRAMMING WORKBENCH

JavaScript / TypeScript

从 JavaScript 运行时进入 TypeScript 类型系统，用模块、异步流程与严格配置构建 Web 应用。

把 JavaScript 的 ESM、Promise 和 npm 工作流与 TypeScript 的类型收窄、运行时验证连接起来，覆盖编译、依赖、测试、常见错误与安全边界。

进入方法库代码仓库官方资料返回专区

MENTAL MODEL / 心智模型

先建立正确的程序直觉

JavaScript 在事件循环上执行；TypeScript 类型在编译后被擦除：它验证代码内部假设，却不能替代对网络、文件和用户输入的运行时校验。

CODE REPOSITORY / 代码仓库锚点

从可测试的目录开始

typescript-project/
├─ package.json
├─ package-lock.json
├─ tsconfig.json
├─ src/index.ts
├─ src/domain.ts
└─ test/domain.test.ts

QUICK START / 第一条命令

先跑通最小闭环

npm init -y && npm install --save-dev typescript && npx tsc --init

LEARNING ROUTE / 学习路径

从写出代码到守住生产边界

每个节点都包含可复制示例、判断原则与常见陷阱。

01常用方法JavaScript 异步流与 TypeScript 收窄 02工程结构严格配置与边界类型 03构建运行类型检查与产物运行 04依赖管理运行包、类型包与版本 05调试测试类型测试与运行时测试 06错误诊断结构类型与模块错误 07安全边界运行时验证与秘密边界

01常用方法

JavaScript 异步流与 TypeScript 收窄

先理解数组、Promise 与事件循环，再用可辨识联合表达有限状态。

异步数据流代码示例

const responses = await Promise.all(urls.map((url) => fetch(url)));
if (responses.some((response) => !response.ok)) {
  throw new Error("request failed");
}

Promise.all 任一失败即拒绝；需要逐项结果时评估 allSettled，并限制并发量。

可辨识联合代码示例

type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: string };

function render(result: Result<User>) {
  return result.ok ? result.value.name : result.error;
}

共同判别字段使控制流分析自动收窄成员。

泛型约束代码示例

function byId<T extends { id: string }>(items: T[]): Map<string, T> {
  return new Map(items.map((item) => [item.id, item]));
}

只声明算法真正需要的约束，避免无意义泛型。

02工程结构

严格配置与边界类型

领域类型归属领域模块，API 输入先验证再进入可信世界。

严格 tsconfig代码示例

{
  "compilerOptions": {
    "target": "ES2022", "module": "NodeNext",
    "moduleResolution": "NodeNext", "strict": true,
    "noUncheckedIndexedAccess": true, "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

模块设置必须匹配实际运行器/打包器；严格选项宜在项目早期启用。

unknown 边界代码示例

function isUser(value: unknown): value is User {
  return typeof value === "object" && value !== null
    && "id" in value && typeof value.id === "string";
}

JSON.parse 的结果应视为 unknown 并运行时校验；复杂 schema 使用成熟验证库。

03构建运行

类型检查与产物运行

区分只检查、输出 JS 和由打包器转换三种流程。

检查与构建终端命令

npx tsc --noEmit
npx tsc -p tsconfig.json
node --enable-source-maps dist/index.js

测试/打包器可能转换 TS 却不做完整类型检查，CI 应单独运行 tsc --noEmit。

开发运行终端命令

npx tsx watch src/index.ts

tsx 是可选开发工具；生产仍应固定构建和运行流程。

04依赖管理

运行包、类型包与版本

确认库是否自带类型，避免运行包和 @types 主版本错配。

依赖分层终端命令

npm install runtime-library
npm install --save-dev typescript @types/node

编译器和纯类型包通常是开发依赖；框架规则可能不同。

可复现安装终端命令

npm ci && npx tsc --noEmit

清单和 lockfile 同步后再合并；升级类型包也需要跑运行时测试。

05调试测试

类型测试与运行时测试

类型检查验证契约，测试 runner 验证真实 JS 行为，二者缺一不可。

运行时测试代码示例

import { strict as assert } from "node:assert";
import test from "node:test";

test("indexes users", () => {
  assert.equal(byId([{ id: "u1", name: "Mikoto" }]).size, 1);
});

按项目运行器配置 TypeScript 转换；不要把“能通过类型检查”当作测试通过。

调试产物终端命令

node --inspect-brk --enable-source-maps dist/index.js

确认 source map 随构建生成且不暴露不应公开的源码。

06错误诊断

结构类型与模块错误

检查推断位置、模块配置与依赖版本，不用 any 一键消音。

not assignable诊断清单

展开源类型与目标类型 → 检查可选字段、readonly、联合成员和 null → 在数据边界转换为领域类型。

as 强制断言不会改变运行时值，应只在已有外部证明时使用。

找不到模块或类型诊断清单

检查 package exports/types → 对齐 module/moduleResolution → 运行 tsc --traceResolution → 确认运行器支持相同模块格式。

编译器能解析不代表 Node/浏览器运行时一定能解析。

07安全边界

运行时验证与秘密边界

类型声明来自开发者，不会净化网络数据、DOM 或数据库结果。

输入校验入口代码示例

const parsed: unknown = JSON.parse(raw);
if (!isUser(parsed)) throw new Error("invalid user payload");
const user: User = parsed;

校验成功后再赋给领域类型；错误信息避免回显敏感原始数据。

安全清单诊断清单

禁止滥用 any/双重断言；DOM 用 textContent；服务端参数化 SQL；秘密不打包进客户端；依赖与生成的 .d.ts 一起审阅。

类型安全是纵深防御的一层，不是授权和验证机制。

PRIVATE CODE VAULT / 私人代码仓库