关于 web-api
web-api 是面向 OpenClaw 的 Web API 设计与实现技能，适用于构建后端服务的开发者。它涵盖 REST、GraphQL 和 tRPC，并包含身份验证、限流与分页指导。
主要功能
- 01设计符合 OpenAPI 3.1 的 REST API
- 02定义 GraphQL 架构与解析器
- 03创建类型化 tRPC 过程
- 04配置 JWT 或 OAuth2 身份验证
- 05实现限流与分页
适用场景
- 01规划带 OpenAPI 规范的后端接口
- 02实现受 JWT 保护的 GraphQL 查询
- 03为用户端点添加分页和限流
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/web-api确认已加载。
详细介绍
web-api
用途
此技能使 OpenClaw 能够使用 REST、GraphQL 和 tRPC 设计并实现 Web API，重点关注 OpenAPI 3.1 规范、JWT/OAuth2 身份验证、速率限制和分页。使用它为 Web 应用生成安全、可扩展的 API 蓝图和代码片段。
使用时机
构建需要 API 端点的后端服务时使用此技能，例如创建用户身份验证系统或获取分页数据。适用于涉及 RESTful 架构、GraphQL 查询或 tRPC 过程的项目，尤其是在需要强制执行速率限制或处理身份验证时。
主要功能
- 使用 OpenAPI 3.1 设计 REST API：使用
openapi-generatorCLI 生成架构，并设置--input spec.yaml --generator spring等标志。 - 实现 GraphQL API：定义架构和解析器，例如使用 Apollo Server 配置：
const typeDefs = gqlquery { users };。 - 处理 tRPC 过程：创建类型化端点，例如
export const appRouter = router({ hello: publicProcedure.query(() => 'world') });。 - 身份验证：通过中间件强制执行 JWT 或 OAuth2；设置环境变量
$WEB_API_JWT_SECRET以签署令牌。 - 速率限制：使用
express-rate-limit等库应用限制，并设置选项{ windowMs: 15*60*1000, max: 100 }。 - 分页：在查询中实现基于游标或偏移量的分页，例如
query { users(first: 10, after: "cursor") }。
使用模式
设计 REST API 时，使用以下命令调用此技能：openclaw run web-api --design rest --spec openapi.yaml。对于 GraphQL，使用：openclaw run web-api --type graphql --schema schema.graphql。始终通过设置 $WEB_API_OAUTH_CLIENT_ID 和 $WEB_API_OAUTH_CLIENT_SECRET 来启用身份验证。对于 tRPC，指定：openclaw run web-api --type trpc --router path/to/router.ts。添加 --rate-limit 100:15m 以启用速率限制。示例 1：若要创建分页用户端点，请运行 openclaw run web-api --design rest --endpoint /users --paginate offset:10，然后集成生成的代码。示例 2：对于安全的 GraphQL 查询，使用 openclaw run web-api --type graphql --auth jwt --query "query { protectedData }"，此命令会输出带有 JWT 验证的解析器。
常用命令/API
- CLI 命令：使用
openclaw run web-api --cluster web-dev --action generate --format openapi创建 OpenAPI 规范文件。 - API 端点：模拟请求，例如发送正文为
{ "username": "user", "password": "pass" }、标头为Authorization: Bearer $WEB_API_JWT_TOKEN的POST /api/v1/login请求。 - 代码片段：REST 服务设置：
app.use(express.json()); app.get('/api/items', (req, res) => res.json(items));。 - 代码片段：GraphQL：
const server = new ApolloServer({ typeDefs, resolvers }); server.listen();。 - 配置格式：OpenAPI 使用 YAML，例如
openapi: 3.1.0 info: title: API paths: /users: get: parameters: - name: page in: query schema: type: integer。 - tRPC 示例：
import { initTRPC } from '@trpc/server'; const t = initTRPC.create(); export const router = t.router({});。
集成说明
通过串联命令将此技能与其他 OpenClaw 技能集成，例如：openclaw run web-api --output code.js; openclaw run database --import code.js。对于身份验证，请确保在运行前已在环境中设置 $WEB_API_API_KEY。与前端技能配合使用时，可将 API 导出为 JSON 架构，供 React 组件使用。通过运行 npm install express graphql @trpc/server 安装依赖项，并在生成的代码中使用 app.use(rateLimit({ max: 100 })); 配置速率限制。可通过导入 OpenAPI 规范，使用 Postman 等工具测试集成。
错误处理
发生错误时，请通过捕获异常来检查常见问题，例如无效的 JWT：try { jwt.verify(token, process.env.WEB_API_JWT_SECRET); } catch (err) { res.status(401).send('Invalid token'); }。对于速率限制，请返回 429 响应并附带 retry-after 标头。使用 OpenClaw 的错误日志：openclaw log error --message "API rate limit exceeded" --skill web-api。解析响应中的 API 错误，例如，如果状态码为 400，则提取错误正文，如 { error: 'Bad request' }。始终使用 try-catch 块包裹 API 调用，并使用环境变量存储敏感数据以避免泄露。
图关系
- 相关：用于 UI 与 API 集成的 "frontend" 技能。
- 关联：用于查询 API 中数据源的 "database" 技能。
- 链接：用于共享 JWT/OAuth2 实现的 "auth" 技能。
- 相关联：用于托管 API 服务的 "deployment" 技能。