ECC 的 TypeScript/JavaScript 模式规范：API 响应、自定义 Hook 与 Repository 模式实战

ECC 的 TypeScript/JavaScript 模式规范：API 响应、自定义 Hook 与 Repository 模式实战

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇技术指南聚焦 ECC（The agent harness performance optimization system）中 docs/ja-JP/rules/typescript/patterns.md 所定义的 TypeScript/JavaScript 核心模式，结合 rules/common/patterns.md 的通用模式骨架，系统讲解 API 统一响应格式、自定义 Hook 模式与 Repository 模式的设计要点、源码级实现依据与实战落地方法。读完本文，你将掌握在 ECC 项目中编写类型安全、可测试、可维护的 TS/JS 代码所需的三个关键模式，并理解它们如何被编码规则、Hook 自动检查与测试体系协同保障。

一、模式文档的定位与适用范围

在 ECC 仓库中，语言规则采用"通用规则 + 语言专属规则"的分层结构。rules/common/patterns.md 定义了所有语言通用的骨架工程策略与设计模式原则，而 rules/typescript/patterns.md（及日文版 docs/ja-JP/rules/typescript/patterns.md）则针对 TypeScript/JavaScript 生态补充了具体实现形态。

这些规则文件通过 frontmatter 声明了生效范围：

--- paths: - "**/*.ts" - "**/*.tsx" - "**/*.js" - "**/*.jsx" ---

即：规则适用于仓库中所有.ts、.tsx、.js、.jsx文件。ECC 自身正是这些模式的实践者——从仓库结构看，scripts/lib、scripts/hooks、tests/lib 等目录下存放着大量 JavaScript 实现与测试，根目录还配有 eslint.config.js 与 package.json 构建工具链，说明这套模式规范直接约束着仓库自身的代码质量。

二、API 响应格式（API Response Format）

2.1 统一信封（Envelope）的设计动机

通用规则 rules/common/patterns.md 指出，所有 API 响应都应使用一致的"信封"结构，其要点包括：

• 包含成功/状态指示符
• 包含数据负载（出错时可为空）
• 包含错误信息字段（成功时可为空）
• 包含分页响应的元数据（total、page、limit）

这种统一封装的价值在于：调用方只需处理一种响应形状，无需为每个接口单独编写解析与错误判断逻辑；分页元数据被固定在同一位置，便于前端表格、无限滚动等通用组件的复用。

2.2 TypeScript 专属实现

TypeScript 版本将通用原则落实为泛型接口：

interface ApiResponse<T> { success: boolean data?: T error?: string meta?: { total: number page: number limit: number } }

要点解读：

• <T>泛型数据负载：data的类型由调用方指定，例如ApiResponse<User[]>表示用户列表响应，ApiResponse<{ token: string }>表示登录响应，保证类型安全的同时保持信封结构统一。
• success: boolean与error?: string互补：成功时error为undefined，失败时data为undefined，二者由success字段驱动消费方的分支逻辑。
• meta可选分页元数据：仅在分页接口中出现；total为总记录数，page为当前页码，limit为每页条数。非分页接口可完全省略meta，保持响应轻量。

2.3 消费侧的类型收窄

结合同族规则 rules/typescript/coding-style.md 中"避免any、用unknown强制安全收窄"的要求，消费ApiResponse的推荐写法是先用success做分支，再访问data：

async function fetchUsers(): Promise<ApiResponse<User[]>> { const res = await fetch('/api/users') return res.json() } const response = await fetchUsers() if (response.success && response.data) { // data 已收窄为 User[]，可安全使用 } else { console.error(response.error ?? 'Unknown error') }

三、自定义 Hook 模式（Custom Hooks Pattern）

3.1 模式价值

自定义 Hook 是 React 生态中复用有状态逻辑（而非 UI）的标准方式。它将定时器、订阅、缓存等副作用逻辑从组件中抽取出来，封装为可独立测试、可跨组件复用的函数。

3.2 官方示例：useDebounce

文档给出了一个完整的防抖 Hook 实现：

export function useDebounce<T>(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState<T>(value) useEffect(() => { const handler = setTimeout(() => setDebouncedValue(value), delay) return () => clearTimeout(handler) }, [value, delay]) return debouncedValue }

实现机制逐行拆解：

1. useState<T>(value)：以初始值初始化内部状态debouncedValue，泛型T保证任意类型的值都可被防抖。
2. useEffect副作用：当value或delay变化时，设置一个setTimeout，在delay毫秒后把最新值写入debouncedValue。
3. clearTimeout(handler)清理函数：这是防抖的核心——每次 effect 重新执行（即依赖变化）时，先清除上一次的定时器。用户连续输入时，旧的定时器不断被取消，直到停止输入delay毫秒后才真正更新状态。
4. 返回值：debouncedValue是"滞后的"稳定值，可直接用于搜索请求、表单校验等昂贵操作。

典型使用场景：

function SearchBox() { const [keyword, setKeyword] = useState('') const debouncedKeyword = useDebounce(keyword, 300) // 仅在用户停止输入 300ms 后才发起搜索 useEffect(() => { if (debouncedKeyword) { search(debouncedKeyword) } }, [debouncedKeyword]) return <input value={keyword} onChange={(e) => setKeyword(e.target.value)} /> }

3.3 配套规则支撑

• rules/typescript/hooks.md 定义了与 Hook/工具调用相关的自动化检查（Prettier 自动格式化、tsc类型检查、console.log告警），确保自定义 Hook 的代码风格与类型正确性在编辑后即被机器校验。
• rules/typescript/coding-style.md 要求组件 props 用命名interface/type显式定义、避免使用React.FC，这些约束同样适用于封装了自定义 Hook 的组件，保证 Hook 的入参出参类型一目了然。

四、Repository 模式（Repository Pattern）

4.1 通用原则

Repository 模式的核心思想是把数据访问封装在统一接口之后。通用规则 rules/common/patterns.md 明确要求：

• 定义标准操作：findAll、findById、create、update、delete
• 具体实现负责存储细节（数据库、API、文件等）
• 业务逻辑依赖抽象接口而非存储机制
• 便于数据源切换与 mock 测试

这样做的收益有两层：可替换性——从内存存储切换到数据库、从 REST API 切换到 gRPC，业务层代码零改动；可测试性——单元测试中注入 mock Repository，即可隔离验证业务逻辑，无需真实数据库。

4.2 TypeScript 专属接口定义

文档给出的接口骨架：

interface Repository<T> { findAll(filters?: Filters): Promise<T[]> findById(id: string): Promise<T | null> create(data: CreateDto): Promise<T> update(id: string, data: UpdateDto): Promise<T> delete(id: string): Promise<void> }

设计要点：

• findAll(filters?: Filters)：可选过滤参数，返回Promise<T[]>，天然适配异步存储（数据库、网络）。
• findById(id: string): Promise<T | null>：返回类型包含null，明确表达"记录可能不存在"这一语义，消费方必须处理未找到的情况，避免undefined隐患。
• create/update的 DTO 分离：CreateDto与UpdateDto通常不同（如创建时必填、更新时可选），文档以独立类型区分，符合"公共 API 显式类型"的编码规范。
• delete(id: string): Promise<void>：删除操作无返回值，语义聚焦于副作用完成。

4.3 一个完整实现示例

interface User { id: string email: string } interface CreateUserDto { email: string } interface UpdateUserDto { email?: string } interface Filters { page?: number limit?: number } // 内存实现：便于测试与原型 class InMemoryUserRepository implements Repository<User> { private users = new Map<string, User>() async findAll(filters?: Filters): Promise<User[]> { return [...this.users.values()] } async findById(id: string): Promise<User | null> { return this.users.get(id) ?? null } async create(data: CreateUserDto): Promise<User> { const user = { id: crypto.randomUUID(), ...data } this.users.set(user.id, user) return user } async update(id: string, data: UpdateUserDto): Promise<User> { const existing = this.users.get(id) if (!existing) throw new Error('User not found') const updated = { ...existing, ...data } this.users.set(id, updated) return updated } async delete(id: string): Promise<void> { this.users.delete(id) } }

注意update中使用了扩展运算符构建新对象而非原地修改，这正是 rules/typescript/coding-style.md 中"不变性（Immutability）"规则的体现。

4.4 与骨架工程策略的衔接

通用模式还定义了"Skeleton Projects"流程：实现新功能时先搜索经过实战检验的骨架工程，用并行 Agent 分别做安全评估、可扩展性分析、相关性评分与实现规划，再克隆最优方案作为基础迭代。Repository 接口恰好构成骨架工程中"数据层"的标准轮廓——新项目只需替换具体实现类，即可沿用同一套接口与业务代码。

五、模式之外：ECC 如何让模式落地

模式定义只是起点，ECC 通过完整的规则体系确保它们被真正执行：

1. 编码风格规则兜底：rules/typescript/coding-style.md 规定公共 API 必须显式标注类型、用interface描述可扩展对象、用type描述联合/交叉/元组、避免any、用 Zod 做输入校验，这些约束直接服务于上述三个模式的可读性与健壮性。
2. Hook 自动化检查：rules/typescript/hooks.md 在~/.claude/settings.json中配置 PostToolUse 钩子（Prettier 自动格式化、tsc类型检查、console.log告警）与 Stop 钩子（会话结束前的console.log审计），让模式违规在编码过程中被即时捕获。
3. 测试体系验证：rules/typescript/testing.md 指定 Playwright 作为关键用户流程的 E2E 测试框架，并由 agents/e2e-runner.md 定义的 e2e-runner Agent 专职执行；Repository 的 mock 可测试性、ApiResponse 的稳定形状，都是 E2E 与单元测试得以高效编写的前提。

从仓库实践来看，ECC 自身在 scripts/lib 与 tests/lib 中大量使用 JS 编写脚本与测试，配合 eslint.config.js 静态检查，正是这套"模式 + 风格 + Hook + 测试"闭环的真实落地场景。遵循本文的三个核心模式，即可在 ECC 生态中写出类型安全、边界清晰、易于替换与测试的 TypeScript/JavaScript 代码。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC