用途:为 Kuroco HeadlessCMS 的 API 设计与实现提供最佳实践,帮助开发者配置端点、选择认证方式并安全地调用 API。可配合 /kuroco-docs 技能检索官方文档;文档未同步时先询问用户是否用 /kuroco-docs 同步,再参考相应文件。
主要能力:
- 端点设计:API 路径形如 https://{站点键}.g.kuroco.app/rcms-api/{api_id}/{endpoint_path};主要配置项包括路径、模型(Topics、Member、InquiryForm 等)、操作(list、details、insert、update、delete)、缓存、流量限制、是否必须认证。
- 认证:管理画面 [API] → [セキュリティ] 提供四种方式。Cookie 认证适合 Web 应用,前端需 credentials: 'include',注意第三方 Cookie 拦截及同域(子域)配置;令牌认证基于 JWT,适合移动应用,取 token 后在请求头加 X-RCMS-API-ACCESS-TOKEN;StaticToken��于服务器间通信或公开 API,固定令牌不要暴露在前端;无认证仅供开发测试。
- 安全:IP 地址限制支持单个 IP、CIDR 和范围;CORS 可配置允许来源、方法、请求头、缓存秒数与凭据;后处理支持输出许可列表、输出转换列表和自定义 Smarty 处理来控制响应字段。
- 缓存与流量:按用途设置缓存时长(如静态内容 86400 秒,实时或需认证的接口设为 0);响应头提供 x-rcms-ratelimit-limit/remaining/reset,429 时应按 reset 秒数重试。
- 调用模式与错误处理:提供列表(含 pageID、cnt 分页,返回 list 和 pageInfo)、filter 条件搜索、详情、插入等调用示例,以及 400/401/403/404/429/500 的对应处理。
限制与注意:资料未提供收费、价格与平台适用范围等信息,暂未提供;具体字段与配置请以官方文档为准。