效率起飞🚀！orpc-contract-first Skills 才是 Dify 前端开发的正确姿势，亲测真香！-Skill优仓

核心功能

在 Dify 的前端开发中，API 接口的管理和类型定义常常让人头大。orpc-contract-first 这个 Skill 简直是为解决这个问题而生的。它不仅仅是一套简单的规则，更是一套完整的契约优先（Contract-First）开发流。

它的核心功能在于强制规范了从契约定义到路由注册，再到 Hook 调用的完整闭环。它要求开发者在 web/contract/ 目录下按照严格的层级结构（Base -> Router -> Domain）来定义 API。通过这种方式，它实现了前端代码与后端接口的强类型绑定。当你使用这个 Skill 时，它会自动引导你完成以下核心操作：

标准化目录结构管理：自动识别并维护 web/contract/console/ 下的业务领域文件，确保代码不乱。
自动化路由注册：在 router.ts 中按 API 前缀（如 billing: {}）进行嵌套组合，拒绝混乱的平铺式路由。
类型安全的 Hooks 生成：基于契约自动推导 React Query 的 Query Key 和 Client 调用方式，彻底告别手动写 TypeScript 类型的痛苦。

实操代码示例

这套 Skills 最香的地方在于它对代码规范的极致要求。看看这个标准的契约定义流程，代码整洁度直接拉满：

首先，在业务领域文件中定义契约（注意输入结构的规范）：

// web/contract/console/billing.ts
import { base } from '../base';
import { type } from '@orpc/contract';

// 定义获取发票详情的路由
export const getInvoice = base.route({
  path: '/invoices/{id}',
  method: 'GET',
  // 强制输入结构：params, query, body
  input: type()
});

然后，在 Router 中进行注册，注意这里严禁使用 Barrel Files（即禁止通过 index.ts 转发导出），必须直接导入：

// web/contract/router.ts
import { invoices } from './console/billing';

export const consoleRouterContract = base.router({
  // 按 API 前缀分组
  billing: {
    invoices
  }
});

最后，在业务组件中调用生成的 Hooks，类型提示会自动跳出来：

// web/service/use-billing.ts
// 自动推导的 Query Key
const queryKey = consoleQuery.billing.invoices.queryKey({ params: { id: '123' } });

// 类型安全的 API 调用
await consoleClient.billing.invoices({ params: { id: '123' } });

优势分析

市面上有很多 API 管理工具，为什么 orpc-contract-first 能脱颖而出？

极致的类型安全：相比于 Swagger 生成代码的笨重，这种契约优先模式让 TypeScript 的类型推导发挥到了极致。InferContractRouterInputs 能直接从路由契约中提取输入输出类型，开发时如果不传参数，IDE 直接报错，将 Bug 拦截在编译阶段。
性能优化的模块导入：许多前端项目因为滥用 Barrel Files（全量导出）导致构建速度变慢。这个 Skills 明确规定禁止 Barrel Files，强制要求直接从具体文件导入，这波操作对 Tree-shaking 非常友好，显著减少了打包体积。
结构清晰的协作模式：对于团队协作来说，统一的 Input structure（params/query/body）和路径参数命名规范，消除了“每个人写接口风格都不一样”的噩梦。

应用场景

这个 Agent Skills 非常适合以下几个高频场景，用起来真的会让你感觉“相见恨晚”：

Dify 前端二次开发：如果你正在对 Dify 平台进行功能扩展，比如增加一个新的“计费模块”或“合作伙伴管理”，这套规范是必须遵守的标准。
遗留 API 迁移重构：当你要把老旧的 service 调用迁移到新的 oRPC 体系时，利用这个 Skill 可以快速建立新契约，逐步替换旧逻辑，风险极低。
大型项目的前后端联调：在 API 变动频繁的迭代期，通过契约文件作为单一真理来源（Single Source of Truth），前端可以配合 TanStack Query 快速响应后端变更，不再需要满世界找接口定义。

最佳实践

想要把 orpc-contract-first 用好，除了遵守基本规则外，还有几个工程化的小技巧：

严格遵守命名规范：文件名建议使用 kebab-case（如 billing-settings.ts），而导出的路由变量名使用 camelCase。这看似小事，但在大型路由注册表中能保持极高的可读性。
类型复用策略：利用 @/types/ 目录集中管理通用领域模型，并在契约定义中通过 type() 泛型传入，避免在契约文件中写死复杂的接口定义，保持契约文件的轻量化。
定期清理路由：随着业务迭代，router.ts 可能会变得臃肿。建议按功能模块（如 console, marketplace）拆分基础路由，保持顶层路由的整洁。

如果你经常在 Dify 生态中进行开发，或者需要在复杂的前端项目中落地强类型的 API 契约，那么这套规范和技巧绝对是你的提效利器。想要获取更多像 orpc-contract-first 这样高质量的 Skills 资源，或者寻找更多关于前端工程化、自动化 Agent 的配置方案，建议去 Skill优仓逛逛。那里汇聚了全网最全的 Skill 智能体资源，无论是学习还是直接复用，都能帮你省下大把时间，真的不要太好用！