skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
tencentblueking/bk-ci55 installs

api-interface-design

设计 BK-CI API 契约时使用,例如 Resource 路径设计、HTTP 方法选择、请求响应对象、错误码和版本策略。当用户要定义接口而不是实现业务逻辑时优先使用。

How do I install this agent skill?

npx skills add https://github.com/tencentblueking/bk-ci --skill api-interface-design
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides API design guidelines and Kotlin code examples for RESTful interfaces. It contains no executable code or security risks.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerwarn

    1/1 file flagged

What does this agent skill do?

API 接口设计

适用场景

  • 设计新的 RESTful API
  • 定义 Resource 接口、请求体和响应体
  • 设计错误码、分页格式和版本策略
  • 评审接口命名和路径结构

不适用场景

  • 实现业务逻辑或服务分层
  • 处理参数校验落地细节
  • 只改前端页面展示

快速指导

  1. 这个 skill 关注的是“接口契约怎么设计”,不是“接口代码怎么实现”。
  2. 设计前先判断调用方是谁,再决定 /user/、/service/、/build/、/open/ 等路径前缀。
  3. 路径、方法、返回结构、错误码和版本策略要作为一套契约一起设计。
  4. 能用资源语义表达的,就不要退化成动作式杂糅接口。
  5. 如果问题已经进入服务分层或实现细节,切到 backend-microservice-development。

高信号规则

  • 接口设计的核心是稳定契约,而不是先把功能堆出来
  • 错误码、分页和返回包装会直接影响前后端协作成本
  • 调用方不同,接口前缀和暴露方式也应不同

关键陷阱

  • 路径命名反映不出资源语义
  • HTTP 方法和真实操作语义不一致
  • 只设计成功响应,不设计错误返回和版本演进

延伸阅读

  • 如果你在实现后端服务:再看 backend-microservice-development
  • 如果你在做参数校验:再看 common-technical-practices

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/tencentblueking/bk-ci/api-interface-design">View api-interface-design on skillZs</a>