Directus GraphQL怎么用 数据查询接口教程

Directus GraphQL是Directus的数据查询接口，可以用GraphQL语法精准查询需要的数据，适合做前后端分离应用。它会根据项目中的集合和字段提供查询能力，你可以在一次请求里指定要取回的字段，避免拿到一大堆暂时用不上的数据。下面从令牌、查询语句和前端请求三个环节开始，带你完成一次常见的文章列表查询。示例中的集合名和字段名需要按你的项目实际结构替换。

第一步：获取API令牌

先登录Directus管理后台，打开角色与权限相关设置，确认用于查询的角色能读取目标集合及所需字段。权限设置要遵循最小范围原则：只开放页面确实要用的数据，避免为了让请求成功而给出不必要的访问权限。接着到用户管理中选择专用API用户，或按项目现有的认证方式创建访问凭证。测试公开内容时，也可以先检查公开角色是否已经开放对应集合的读取权限。

如果使用静态令牌，在用户设置中生成或配置令牌，并在本地开发环境中妥善保存。不要把管理账号的凭证直接写进网页代码，也不要把静态令牌提交到公开代码仓库；浏览器里的代码对访问者可见。正式项目通常由后端保管机密令牌，再由后端根据业务需要访问Directus。记下项目域名和GraphQL接口地址，常见接口路径为 /graphql，实际地址以你的部署配置为准。

第二步：编写GraphQL查询

打开支持GraphQL的客户端，或在项目中使用GraphQL请求工具，先向项目的GraphQL接口发送一个最小查询。Directus会根据集合生成对应的查询字段；例如集合名为 articles 时，可以从查询根字段 articles 开始，再在大括号里列出希望返回的字段。以下查询请求文章的编号、标题和发布时间：query { articles { id title date_created } }。若项目字段名不同，先在后台核对集合结构，再修改查询里的名称。

查询成功后，响应通常会在 data 对象下按查询结构返回结果。若只想获取指定文章，可以在查询中使用项目支持的过滤参数；查询字段、过滤运算符和参数类型都要与Directus生成的GraphQL模式匹配。编写时先从一两个字段开始测试，确认集合名称拼写正确、字段可读，再逐步加入关联字段。若出现权限错误，优先检查角色权限；若提示字段未知，则检查集合名和字段名。

使用过滤和排序参数

过滤适合从集合中挑出符合条件的记录。例如只查标题等于“入门教程”的文章，可写成 query { articles(filter: { title: { _eq: “入门教程” } }) { id title } }。常用运算符包括相等、包含和大小比较，具体可用项以当前项目的GraphQL模式为准。多个条件可以组合，但建议先单独测试每项过滤，避免条件写错后误以为接口没有数据。过滤字段也必须具有读取权限。

排序和分页可以放在集合查询参数中。例如按创建时间倒序并限制返回数量，可写成 query { articles(sort: [“-date_created”], limit: 10) { id title date_created } }。负号表示倒序，limit控制本次最多返回多少条；翻页时可以配合offset跳过前面的记录。列表页应设置合理的返回上限，不要一次请求整个大型集合。若排序结果不符合预期，确认排序字段存在，并查看该字段的值是否为空。

第三步：在前端调用API

前端调用时，将查询语句作为POST请求的JSON内容发送到 /graphql，并设置 Content-Type 为 application/json。需要认证时，再按所用认证方式附上Authorization请求头，例如Bearer令牌。示意请求体为 {“query”:”query { articles(limit: 10) { id title } }”}。使用fetch时，记得检查HTTP状态码，并解析返回的JSON；GraphQL也可能在响应中返回errors字段，因此不能只看请求是否成功发出。

实际接入时，可以把接口地址放在环境配置中，把查询封装成独立函数，并在页面加载时调用。页面应分别处理加载中、查询成功、空列表和错误状态，方便用户理解当前情况。浏览器端不要放置有高权限的静态令牌；如需要这类凭证，应通过可信后端代理请求。完成后用浏览器开发者工具检查请求地址、请求体和响应内容，再逐项确认过滤、排序及分页是否符合预期。

如果想快速搭建面向国内团队的原型页面，也可以了解墨刀AI，官网地址为modao.cgref.cn。无论采用哪种工具，接入Directus前都应先确认它支持的请求方式、鉴权配置和数据权限策略。教程页面由润灭整理；上线前建议在测试环境验证查询，并按实际角色权限检查接口返回，确保页面只展示预期的数据。