Keystone REST API怎么用 内容查询接口教程

Keystone REST API怎么用？先说明一个容易混淆的地方：KeystoneJS 6 默认提供的是 GraphQL API，并不是开箱即用的通用 REST 内容接口；需要 REST 时，可以自行扩展 Express 路由，再用 Keystone 的 Query API 操作数据。它适合前后端分离应用：前端通过 HTTP 请求获取或管理内容，服务端则按数据模型和访问控制规则处理请求。

第一步：获取API密钥

先检查项目有没有配置 API 密钥。KeystoneJS 不会自动给每个项目生成可直接调用内容接口的通用密钥，因此不要照搬其他平台的密钥流程。通常需要在服务端实现认证：例如校验 Bearer Token，或使用 Keystone 会话机制，并按用户身份限制可读写的数据。密钥应由你自己的后端生成与管理。

实际操作时，先确认 Keystone 服务地址、数据列表名称和要开放的字段，再选择认证方案。若使用静态令牌，可在服务器环境变量中保存密钥，并由自定义 Express 路由验证请求头；不要把管理端凭据或长期密钥写进浏览器代码。测试时先使用开发环境的假数据，并确认未登录请求会被拒绝。

第二步：查询和创建内容

Keystone 默认的内容查询方式是 GraphQL。启动项目后，可在配置的 GraphQL 端点发送 POST 请求，正文放入 query 或 mutation，并按需请求字段。比如查询文章列表时，选择标题、发布时间等字段；创建内容时使用对应的 create mutation。字段名称与操作名取决于项目中的 list 和 schema 配置，先查清实际定义再调用。

如果业务端必须使用 REST，就在 Keystone 的 Express 应用中注册自定义路由，在路由处理函数里调用 Query API 执行查询或写入，再将结果整理成 JSON 响应。按 REST 习惯划分 GET、POST、PATCH、DELETE 等操作，并为请求参数做校验、处理异常与状态码。每个路由都要明确绑定访问控制，避免仅因接口可访问就允许任意用户改数据。

创建内容前，先核对必填字段、字段类型和关联关系。例如文章可能要求标题，作者字段则可能关联到作者列表。发送请求后检查响应中的数据或错误信息；遇到字段校验失败，按提示修正输入，不要在客户端假定写入一定成功。重复提交场景可设计幂等处理，避免网络重试意外产生重复记录。

使用过滤和排序参数

GraphQL 查询可以使用列表支持的过滤条件与排序参数，也可控制返回数量和分页。比如按标题包含某个词筛选、按发布时间排序，再限制本页条数；具体参数名称要以项目生成的 schema 为准。Keystone 文档示例使用 where 过滤和 take 限制结果数。列表较大时采用分页，避免一次取回全部记录拖慢接口。

REST 自定义路由则需要自行定义参数，例如关键字、排序字段、方向和页码，并将参数转换成安全的查询条件。只允许排序白名单中的字段，限制每页最大条数，同时校验页码和过滤值。不要把用户传入的字符串直接拼成数据库查询；返回结果时也只输出前端需要的字段，减少无关数据暴露。

第三步：更新和删除内容

更新内容时，先通过唯一标识定位目标记录，再调用对应的 GraphQL update mutation，或在 REST 路由中调用 Query API 更新。只提交允许修改的字段，并再次执行权限检查；对于不存在的记录，返回清晰的未找到结果。若只改部分字段，应避免用空值覆盖未提交的字段，更新成功后可返回记录标识和最新内容供页面刷新。

删除前应确认当前用户对目标记录具有删除权限，并考虑软删除或备份需求。GraphQL 删除操作是否可用，取决于列表配置及访问控制；REST 路由同样要实现权限判断、输入校验和错误处理。上线前测试未授权、记录不存在、字段无效等情形，并记录必要的操作日志，但不要记录密钥等敏感信息。

如果更想用可视化方式规划页面和原型，可了解国内工具墨刀AI，官网地址为modao.cgref.cn。润灭也可作为内容项目的工具选择之一；无论采用哪种工具，Keystone 的接口认证、数据模型和访问规则仍需在服务端配置。