Cockpit REST API 完全指南从 API Key 认证到高级查询的 10 个实战技巧【免费下载链接】CockpitCockpit Core - Content Platform项目地址: https://gitcode.com/gh_mirrors/cockp/CockpitCockpit 是一个开源的轻量级内容平台Cockpit Core - Content Platform它把内容建模、发布与管理融为一体并内置了一整套完善的 REST API 和 GraphQL 接口。无论你是前端开发者、移动端工程师还是自动化脚本爱好者只需要一个 API Key就能把 Cockpit 里的内容安全地取出来、写进去。这份 Cockpit REST API 完全指南将从 API Key 认证讲起一步步带你掌握过滤、排序、分页、关联填充等高级查询技巧用 10 个实战技巧帮你快速上手少走弯路。技巧 1先搞懂 Cockpit REST API 的整体架构Cockpit 的 REST API 不是插件式的附加功能而是平台的核心服务。所有/api/*路径的请求都会经过统一的认证与授权拦截认证通过后分发到具体的端点处理路由绑定与 API Key 校验发生在 modules/App/api.php这是理解整个认证流程的入口文件REST 端点由App\RestApi\Query服务统一注册与调度核心逻辑在 modules/App/RestApi/Query.php各模块通过restApi.config事件注册自己的端点例如内容模块的全部接口都定义在 modules/Content/api.php记住这个三层结构入口绑定 → 服务分发 → 模块端点后面排查问题会非常方便。技巧 2创建 API Key——认证的第一步在正式调用接口前你需要先拥有一个 API Key。操作路径很简单登录 Cockpit 后台 → System系统模块 → API 管理 → 新建密钥填写名称后保存即可。密钥本质上是一条存在system/api_keys集合里的记录包含key、name、role角色和meta等字段。如果你好奇后端的处理逻辑可以查看 modules/System/Controller/Api.php 中的save、remove和load方法。 小提示API Key 的角色role决定了它能访问哪些内容模型配置 ACL 时建议遵循最小权限原则。技巧 3三种传递 API Key 的方式总有一种适合你拿到密钥后Cockpit REST API 认证支持三种传递方式你可以按场景任选其一请求头传递在 Header 中加入api-key: 你的密钥官方 OpenAPI 文档约定的标准方式Bearer Token 传递在 Header 中加入Authorization: Bearer 你的密钥查询参数传递直接在 URL 上加?api_key你的密钥适合快速测试这三种方式在入口处会被统一识别具体逻辑见 modules/App/api.php 第 32 行附近的 token 解析代码。技巧 4用 public 密钥实现匿名访问如果你的网站有公开栏目的需求比如新闻列表、产品展示不必为每个访客创建账号。Cockpit 内置了一个特殊的public密钥当请求没有携带任何 token 时系统会自动以public身份访问配合 ACL 把某些模型设置为可读即可。这样一来前端页面甚至不需要带密钥就能拉取公开内容同时后端仍然能严格拦截未授权的模型。技巧 5用USR-前缀密钥模拟真实用户有些场景下你需要以某个用户的角色来调用接口例如返回该用户专属的内容。Cockpit 支持在用户资料中配置一个以USR-开头的 apiKey调用时携带它系统就会把该用户的role和_id注入到本次请求中。认证代码在 modules/App/api.php 中通过正则^USR-识别这种密钥并直接从system/users集合中查出对应用户。⚠️ 注意目前 JWT 形式的 token 会被系统直接拒绝返回 401这是为了防止认证绕过请使用 API Key 体系。技巧 6快速获取自动生成的 OpenAPI 接口文档不想死记端点Cockpit 会在运行时自动扫描各模块的OA注解生成标准 OpenAPI 规范文档YAML 格式GET /system/api/openapi?formatyamlJSON 格式GET /system/api/openapi?formatjson这套文档由 modules/System/Controller/Api.php 中的openapi方法生成并借助 lib 目录下的 SwaggerPhp 解析器完成注解扫描。更贴心的是后台还内置了 REST API 在线调试器rest-api-viewer粘贴密钥后可以直接在网页里发请求、看响应调试效率翻倍。技巧 7filter 参数——精确查询的核心查询列表时最强大的武器是filter参数。它接收一段URL 编码后的 JSON语法与 MongoDB 查询风格一致支持$eq、$ne、$gt、$lt、$in、$regex等常用操作符。例如筛选状态为已发布且标题包含教程的文章GET /api/content/items/articles?filter{title:{$regex:教程},_state:1}内容模块对 filter、fields、sort 等参数都会做 JSON 解析与合法性校验解析失败会返回 400 错误具体实现可参考 modules/Content/api.php 中/content/items/{model}端点的处理逻辑。另外注意REST API 默认只返回已发布内容_state 1草稿不会被泄露这是平台默认的安全策略。技巧 8fields 字段投影让响应瘦身如果你的模型字段很多但前端只需要其中两三个就可以用fields参数做字段投影只返回需要的字段既省流量又加快渲染GET /api/content/items/articles?fields{title:1,summary:1}字段投影同样以 URL 编码 JSON 形式传入写法直观和 Mongo 的 projection 完全一致。技巧 9sort、limit 与 skip——排序与分页的正确姿势列表接口支持三个配套参数sort控制排序如{_created:-1}按创建时间倒序limit限制返回条数skip跳过前 N 条实现翻页。当你同时传了skip和limit时接口会返回一个带元信息的分页结构{ data: [...], meta: { total: 128 } }meta.total是符合当前筛选条件的总条数前端拿它做分页组件再合适不过。这种一条接口完成筛选排序分页的设计让 Cockpit REST API 在查询大数据量时依然游刃有余。技巧 10populate、aggregate 与树形查询——高级玩法进阶最后三个进阶能力能让你的接口调用更上一层楼populate 关联填充当模型里有指向其他模型的关联字段时加populate1或更大的深度值即可让接口自动把关联内容一并返回免去多次请求非常适合构建嵌套的文章-作者-标签结构。aggregate 聚合管道GET /api/content/aggregate/{model}?pipeline[...]支持传入 Mongo 风格的聚合管道可以做分组统计、计数、求和等数据分析。出于安全考虑平台已禁用$out和$merge两个写库阶段防止通过 API 覆盖数据。tree 树形查询对 tree 类型的模型用GET /api/content/tree/{model}可以按层级拉取整棵内容树配合parent参数还能按父节点定向查询。除此之外Cockpit 还提供了 GraphQL 服务端点/api/gql支持 multipart 文件上传schema 由模型自动生成与 REST API 互为补充。需要了解内容模块的完整端点清单直接阅读 modules/Content/api.php 的注解即可。写在最后从创建 API Key 到完成认证从基础过滤到聚合管道Cockpit REST API 的设计思路始终是开箱即用、安全默认。这 10 个实战技巧覆盖了日常开发中 90% 以上的使用场景先用public密钥跑通公开内容再用api-key头完成受保护接口的认证最后用 filter、fields、populate 组合出高效的查询。当你需要更复杂的数据加工时别忘了还有 aggregate 和 GraphQL 这两张底牌。现在就打开你的 Cockpit 后台创建一个 API Key开始你的第一个 REST 请求吧【免费下载链接】CockpitCockpit Core - Content Platform项目地址: https://gitcode.com/gh_mirrors/cockp/Cockpit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考