AI 技能AI 插件人工智能【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills点击查看免费下载本文聚焦 AASagentic-awesome-skills仓库内api-patterns技能中的 tRPC 设计原则文档系统梳理 tRPC 的适用场景、核心收益与集成方式并结合同技能下的 API 风格决策树、版本管理策略与启发式校验脚本给出可落地的 TypeScript 单仓库 API 设计实践。读完本文你将能够判断一个项目是否适合 tRPC、如何在 REST/GraphQL/tRPC 之间做出选择并理解类型安全与运行时校验的边界。一、tRPC 原则文档定位不复制模式而是学会思考在 AAS 仓库中api-patterns是一个面向 API 设计决策的技能模块其入口文件 SKILL.md 明确写道API design decisions tied to the consumers and deployment constraints. Learn to THINK, not copy fixed patterns.API 设计决策要绑定消费方与部署约束学会思考而不是复制固定模式。本技能采用选择性阅读规则Selective Reading Rule维护了一张内容地图文件说明何时阅读api-style.mdREST vs GraphQL vs tRPC 决策树选择 API 类型时rest.md资源命名、HTTP 方法、状态码设计 REST API 时response.md信封模式、错误格式、分页设计响应结构时graphql.mdSchema 设计、适用时机、安全性考虑 GraphQL 时trpc.mdTypeScript 单仓库、类型安全TS 全栈项目时versioning.mdURI/Header/Query 版本管理API 演进规划时auth.mdJWT、OAuth、Passkey、API Keys认证模式选择时rate-limiting.md令牌桶、滑动窗口API 防护时documentation.mdOpenAPI/Swagger 最佳实践文档化时security-testing.mdOWASP API Top 10、认证/授权测试安全审计时trpc.md 正是这张地图中针对TypeScript 全栈项目的一张专章它不去罗列 tRPC 的全部 API而是给出何时该用、何时不该用、用它能得到什么、常见的集成拓扑这四组判断依据帮助开发者在具体约束下做选择。二、何时使用 tRPC完美契合与明显不适原文档用一组清晰的对比清单给出适用性判断。完美契合的场景Perfect fit✅ Perfect fit: ├── TypeScript on both ends 两端都是 TypeScript ├── Monorepo structure 单仓库monorepo结构 ├── Internal tools 内部工具 ├── Rapid development 快速迭代开发 └── Type safety critical 类型安全至关重要明显不合适的场景Poor fit❌ Poor fit: ├── Non-TypeScript clients 非 TypeScript 客户端 ├── Public API 公开 API ├── Need REST conventions 需要 REST 约定 └── Multiple language backends 多语言后端逐条展开理解两端 TypeScript 是前提tRPC 的端到端类型推断依赖前端与后端共享同一套 TypeScript 类型。只要有一端不是 TypeScript例如 Swift/Java 原生客户端、Python 后端类型收益就会大打折扣此时应优先考虑 REST OpenAPI。单仓库是放大器前后端代码同仓才能直接import type共享类型如果前后端分仓部署、各自独立发布构建期共享的类型无法保证线上已部署客户端与新版服务端仍然兼容这一点原技能在 SKILL.md 的 Limitations 与 versioning.md 中反复强调。内部工具与快速迭代没有公开契约的兼容性包袱、变更频繁、团队小步快跑正是 tRPC 低摩擦特性的用武之地。类型安全关键当改一处类型全链路报错的价值大于接口文档维护成本时tRPC 优势明显。反之公开 API 需要面向未知的、多语言的外部消费方REST OpenAPI 的兼容面更宽多语言后端则无法享受单一类型源带来的收益。三、tRPC 的核心收益从共享类型到全链路类型推断原文档总结的五条收益构成了 tRPC 的选型价值主张Why tRPC: ├── Shared TypeScript types; still validate untrusted runtime input │ 共享 TypeScript 类型但依然要校验不可信的运行时输入 ├── End-to-end type inference │ 端到端类型推断 ├── IDE autocomplete across stack │ 跨栈 IDE 自动补全 ├── Type errors surface for clients rebuilt against the shared contract │ 针对共享契约重新构建的客户端会浮出类型错误 └── No code generation step │ 无需代码生成步骤这五条收益中共享类型≠安全是最容易被误读的一点也是本技能反复强调的核心认知类型只在编译期生效。tRPC 的类型推断把前端调用签名与后端 procedure 定义绑定在一起前端重新构建时接口变更会立刻表现为 TypeScript 编译错误——这是共享契约带来的构建期保护。运行时输入永远不可信。HTTP 请求到达服务端时任何字段都可能被篡改。因此 tRPC 生态通常搭配 zod 之类的 schema 校验库对输入做运行时验证。这一点可以直接在仓库的校验脚本中得到印证api_validator.py 在check_api_code中把zod、joi、yup、validate、schema、pydantic等关键词列为输入校验Input validation的判定模式——也就是说tRPC 项目同样要求显式的输入校验证据类型推断本身不算校验。tRPC 推断不强制执行授权与兼容性。原技能 SKILL.md 的 Limitations 明确写道GraphQL query shape, tRPC inference and HTTP method names do not enforce resource authorization or backwards compatibility.GraphQL 查询形态、tRPC 类型推断与 HTTP 方法名都不会强制执行资源授权或向后兼容。类型安全解决的是编译期错配而授权、限流、兼容性需要单独设计。关于无代码生成步骤相比 gRPC需 protoc 生成桩代码或部分 GraphQL 工具链需 codegentRPC 通过 TypeScript 的类型推断直接把服务端 procedure 的类型推导到客户端无需额外生成层。这降低了工具链复杂度也是快速开发定位的重要来源。需要说明的是无需生成不等于没有契约——契约就是两端共享的 TypeScript 类型本身。四、常见集成模式从 Next.js 到任意 TS 前端原文档给出了四类常见集成拓扑Common setups: ├── Next.js tRPC (most common) 最普遍 ├── Monorepo with shared types 单仓库 共享类型 ├── Remix tRPC └── Any TS frontend backend 任意 TS 前端 后端Next.js tRPCtRPC 官方文档中覆盖最充分的组合App Router 下的 server/client 边界与 tRPC 的 procedure 分层天然契合是社区最常见的落地形态。Monorepo with shared types这是 tRPC 最佳实践的核心形态——在单仓库中抽取一个共享类型包通常是repo/validators或repo/types前端只import type后端在 procedure 中输入输出引用同一类型源实现单一事实来源。Remix tRPC / 任意 TS 前端tRPC 的客户端基于createTRPCProxyClient的 fetch/HTTP 适配器不绑定特定框架只要是 TypeScript 前端都可以通过 tRPC client 获得相同的类型推断收益。无论哪种拓扑都需要遵循本文第三节的原则共享类型只覆盖编译期procedure 内部依然要对输入做运行时校验、对操作做授权控制。五、放进决策树REST vs GraphQL vs tRPCtRPC 不是银弹它的位置由消费方形态决定。api-style.md 提供的决策树在谁在使用 API这一问题上给出了明确的路径Who are the API consumers? │ ├── Public API / Multiple platforms │ └── REST OpenAPI (widest compatibility) │ ├── Complex data needs / Multiple frontends │ └── GraphQL (flexible queries) │ ├── TypeScript frontend backend (monorepo) │ └── tRPC (end-to-end type safety) │ ├── Real-time / Event-driven │ └── WebSocket AsyncAPI │ └── Internal microservices └── gRPC (performance) or REST (simplicity)即当且仅当TypeScript 前端 后端 单仓库时tRPC 才进入候选。同文档的三方对比表把这种差异量化因素RESTGraphQLtRPC最适合公开 API复杂应用TS 单仓库学习曲线低中低若熟悉 TS过取/欠取over/under fetching为消费方定制端点形态客户端自选字段需强制成本限制取决于 procedure 设计类型安全手动OpenAPI基于 Schema自动缓存HTTP 原生复杂基于客户端值得注意 tRPC 一栏的两条过取/欠取取决于 procedure 设计与缓存基于客户端。tRPC 没有 GraphQL 的字段选择能力也没有 REST 的 HTTP 缓存语义如 GET 的 ETag/304因此若要避免过度取数需要在后端设计粒度合适的 procedure细粒度查询 组合这是 API 设计者的职责类型推断不会替你解决缓存策略需要自行设计如trpc-panel、浏览器 HTTP 缓存、React Query 的客户端缓存等。选择前建议回答 api-style.md 给出的五个筛选问题谁在消费这个 API前端是 TypeScript 吗数据关系有多复杂缓存是否关键是公开 API 还是内部 API只要第 2、5 题分别回答是与内部第 1、3、4 题的答案通常都会把天平推向 tRPC。六、tRPC 与版本管理类型只保证构建期tRPC 项目同样面临 API 演进问题而版本管理的哲学在此有特殊性。versioning.md 给出的四种策略各有取舍策略实现权衡URI/v1/users清晰、易缓存HeaderAccept-Version: 1URL 更干净、但难以发现Query?version1易添加、但混乱无谨慎演进内部最佳公开有风险其中与 tRPC 直接相关的一条哲学是tRPC? → Test deployed-client compatibility; types only help at build time 测试已部署客户端的兼容性类型只在构建期起作用这是 tRPC 版本管理的关键提醒类型系统无法保护已经部署到线上的旧客户端。当你在单仓库中修改了一个 procedure 的输入输出类型本地前端重新构建会立即报错——但线上仍然在跑旧版本前端的用户不会得到任何编译期保护。因此内部快速迭代时可以不做显式版本号靠谨慎演进只做向后兼容的加法式变更但只要存在独立部署、独立发布节奏的客户端就应该考虑 URI 版本化并对已部署客户端的兼容性做真实测试而不是依赖tsc通过就放行。七、决策清单与反模式把 tRPC 选型纳入完整流程SKILL.md 提供了在设计任何 API含 tRPC之前应完成的决策清单是否询问了 API 消费方是否为当前上下文选择了 API 风格REST/GraphQL/tRPC是否定义了统一的响应格式是否规划了版本化策略是否考虑了认证需求是否规划了限流是否确定了文档化方案同时要避开反模式Anti-Patterns不要做DONT对一切场景默认使用 REST在 REST 端点中使用动词如/getUsers返回不一致的响应格式向客户端暴露内部错误跳过限流。应当做DO基于上下文选择 API 风格询问客户端需求充分文档化使用恰当的状态码。把这些映射到 tRPC 项目上即便你选定了 tRPC依然要定义统一错误格式如 tRPC 的 error formatter、规划 procedure 的认证中间件与限流、并保证输入校验zod到位——tRPC 只是替换了契约传输层它没有替你完成其余六项 API 工程责任。八、用仓库校验脚本做实现后的自查原技能还附带了一个本地启发式扫描脚本 scripts/api_validator.py运行方式为python3 skills/api-patterns/scripts/api_validator.py project_path脚本会从目标项目中发现 API 相关文件*api*.ts/js/py、routes/、controllers/、endpoints/、openapi.json/yaml、swagger等最多采样 15 个文件并排除node_modules、.git、dist、build、__pycache__随后用正则做浅层检查错误处理try {、.catch(、except、catch(状态码status(3xx)、HttpStatus.、res.status(等输入校验validate、schema、zod、joi、yup、pydantic、Body(、Query(认证/授权auth、jwt、bearer、token、middleware、guard限流rateLimit、throttle日志console.log、logger.、log.。必须明确脚本的边界正如脚本头注释所写它是 Heuristic triage启发式分流不是 schema 验证更不是安全审计或部署审批。对一个 tRPC 项目而言脚本在输入校验一栏能否命中zod模式恰好可以作为你是否真的对 procedure 输入做了运行时校验的快速佐证——但[OK]只代表正则命中不代表校验逻辑正确。SKILL.md 的 Limitations 也提醒限流无法单独防止所有资源耗尽还需考虑大小、并发、时间与供应商成本边界安全类检查只能在授权范围内对本地/测试目标进行。九、结语tRPC 是契约策略不是安全策略AAS 的 trpc.md 用一份精炼的原则清单回答了三个问题何时用TS 两端 单仓库 内部 快迭代 类型安全关键、为何用共享类型 端到端推断 无 codegen、怎么集成Next.js/单仓库/Remix/任意 TS 前端。而把它放回api-patterns技能整体来看结论会更加完整tRPC 解决契约层问题它让前后端共享的 TypeScript 类型成为单一事实来源把接口错配提前到编译期类型安全 ≠ 输入安全运行时校验zod 等与授权控制是强制义务tRPC 推断本身不提供构建期 ≠ 生产期已部署客户端的兼容性需要显式测试与版本策略不能依赖tsc选型先问消费方公开 API 选 REST OpenAPI、复杂查询多前端选 GraphQL、TS 全栈单仓库选 tRPC决策树与对比表是判断依据。最终回归技能入口的那句话学会思考而不是复制固定模式。tRPC 原则文档提供的正是这种在约束下做选择的思考框架——类型推断帮你把契约钉死在两端而其余 API 工程责任校验、授权、限流、版本、文档依然需要你逐项落实。赞分享AI 技能AI 插件人工智能【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills点击查看免费下载相关推荐如何用Next.js与TRPC构建端到端类型安全API完整指南如何用Next.js与TRPC构建端到端类型安全API完整指南 Next.js作为React框架的佼佼者为开发者提供了构建全栈应用的强大能力。而TRPCT前端Web框架SSR后端tRPC-Nuxt构建端到端类型安全的APItRPC Nuxt构建端到端类型安全的API 项目介绍 tRPC Nuxt 是一个专为 Nuxt 应用程序设计的开源项目旨在通过 tRPC.io httpsTypeScript与TRPC终极指南构建端到端类型安全API的完整教程TypeScript与TRPC终极指南构建端到端类型安全API的完整教程 TypeScript作为现代前端开发的标配与TRPC框架的完美结合为开发者提供了文档教程上一篇极速Markdown解析Ink Swift库完全指南下一篇Nanoid.NET教程生成唯一ID的利器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考