mcpField
Q
quality-code

quality-code

github.com/rhyssullivan开发104235 次安装16 周前更新
代码仓库

关于 quality-code

面向全栈 TypeScript 开发者的编码与审查指南，强调用类型表达有效状态、端到端传递类型，并采用真实服务测试和 OpenTelemetry。

主要功能

  1. 01用品牌类型和联合类型约束状态
  2. 02端到端共享并推导类型
  3. 03优先使用对象参数
  4. 04采用 Standard Schema 验证
  5. 05用真实服务进行测试
  6. 06以 OpenTelemetry 追踪观测

适用场景

  1. 01设计更难进入无效状态的 API
  2. 02减少客户端与服务端类型重复
  3. 03为共享验证逻辑接受通用 Schema
  4. 04测试数据库及本地云服务交互

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rhyssullivan/skills --skill quality-code

安装后在 Claude Code 中输入/quality-code确认已加载。

详细介绍

编写高质量的全栈 TypeScript

编写或审查 TypeScript 代码时，请遵循以下原则。

让不可能的状态无法表示

利用类型系统，让无效状态在编译时就报错。可达状态越少，代码就越容易阅读和修改。

品牌类型

为基础类型添加品牌，避免它们混淆。在边界处验证一次；下游代码可以信任该类型。

type PhoneNumber = string & { __brand: "PhoneNumber" };

function parsePhone(input: string): PhoneNumber {
  if (!/^\+?\d{10,15}$/.test(input)) throw new Error(`Invalid: ${input}`);
  return input as PhoneNumber;
}

function sendSMS(to: PhoneNumber, body: string) {
  /* input is trusted */
}

如果项目已经使用支持原生品牌类型的库（例如 Effect），请使用其基础类型，而不是自行实现。

优先使用可辨识联合类型，而非标志集合
// Don't — invalid combos representable
type State = { loading: boolean; user?: User; error?: string };

// Do — only valid states exist
type State =
  | { status: "loading" }
  | { status: "success"; user: User }
  | { status: "error"; error: string };

让类型贯穿整个流程

数据库架构 → 服务端 → 客户端应共享类型，无需手动重复定义。使用项目已有的端到端类型工具（tRPC、oRPC、Elysia、TanStack Start 等）。标记为 Email 品牌类型的 users.email 到达客户端时也应保留该品牌类型。

不要重复声明可以推导出的类型。编写新接口前，先考虑使用 Pick、Omit、Parameters、ReturnType、Awaited、typeof 等。对于函数参数，应从源头推导，而不是手动指定类型：

// Don't — duplicate shape, drifts when the row changes
type UserSummary = { id: string; email: Email };
function renderUser(u: UserSummary) {
  /* ... */
}

// Do — derive from the source of truth
type User = Awaited<ReturnType<typeof db.query.users.findFirst>>;
function renderUser(u: Pick<User, "id" | "email">) {
  /* ... */
}

传递对象，而不是位置参数

// Don't — swap two args, still compiles
sendEmail("Welcome!", "Hi there");
// Do — order-independent, self-documenting
sendEmail({ to: "[email protected]", body: "Hi there" });

在对性能至关重要的热点路径中跳过此做法；其他情况下默认采用。

使用 Standard Schema 实现共享验证

对于不想选定某个验证器的库或代码，请接受 StandardSchemaV1<unknown, T>。

尽可能进行真实测试

能实际运行的东西就不要模拟。启动真实服务：

  • 使用 LocalStack 测试 AWS
  • 使用 Miniflare 测试 Cloudflare Workers
  • 使用真实的 Postgres/SQLite（例如 bun:sqlite），而不是模拟数据库

仅模拟没有测试环境的第三方服务。

使用 OpenTelemetry，而不是打印日志

添加可观测性时，请使用 OTel span 进行埋点。首次有用户发送请求 ID 时，你就能直接找到答案，而不是靠猜测——这笔配置成本便物有所值。

评论

支持 Markdown