Grafbase项目发布0.25.0版本：增强可信文档的渐进式采用能力

Grafbase是一个现代化的GraphQL网关解决方案，它帮助开发者构建、部署和管理GraphQL API。作为GraphQL生态中的重要工具，Grafbase提供了强大的功能来优化API性能、安全性和可维护性。

可信文档功能的渐进式采用策略

在最新发布的0.25.0版本中，Grafbase对可信文档(Trusted Documents)功能进行了重要改进，使其支持更加灵活的渐进式采用策略。可信文档是GraphQL API安全性的重要组成部分，它通过预先注册和验证查询来防止恶意查询和查询注入攻击。

配置选项的扩展

新版本引入了更细粒度的配置选项，允许团队根据实际需求逐步实施可信文档策略。在grafbase.toml配置文件中，现在可以设置以下参数：

[trusted_documents]
enabled = true
enforced = true
bypass_header_name = "my-header-name"
bypass_header_value = "my-secret-is-{{ env.SECRET_HEADER_VALUE }}"
document_id_unknown_log_level = "error"
document_id_and_query_mismatch_log_level = "off"
inline_document_unknown_log_level = "warn"

渐进式采用的三阶段

1. 监控阶段：仅设置enabled = true时，网关会获取并缓存可信文档，但不强制执行。这允许团队收集数据并了解当前查询使用情况。

2. 过渡阶段：通过配置不同的日志级别，团队可以监控潜在问题。例如，设置document_id_unknown_log_level = "warn"可以在控制台看到哪些文档ID未被识别，而不会中断服务。

3. 强制执行阶段：当enforced = true时，网关将完全实施可信文档策略。新版本还放宽了对仅包含内联文档请求的限制，为迁移提供了更大的灵活性。

日志级别的精细控制

新版本引入了三种专门的日志级别设置，帮助团队更好地监控和调试可信文档的使用情况：

1. 未知文档ID日志：记录请求中包含文档ID但找不到对应可信文档的情况。

2. 文档ID与查询不匹配日志：记录同时发送查询文档和文档ID时，获取的可信文档与内联查询不匹配的情况。

3. 内联文档未知日志：记录发送内联文档但找不到匹配可信文档的情况。

每种日志都可以独立配置为off、error、warn、info或debug级别，默认均为info级别。

其他改进

除了可信文档功能的增强外，0.25.0版本还修复了@skip和@include指令在反序列化子图响应时可能不被正确处理的问题，进一步提高了GraphQL查询的准确性和可靠性。

总结

Grafbase 0.25.0版本通过引入可信文档的渐进式采用策略，为团队提供了更平滑的迁移路径。这种分阶段的方法降低了采用门槛，使组织能够在不中断现有服务的情况下逐步提高API安全性。同时，精细的日志控制为监控和调试提供了强大工具，确保在完全强制执行前发现并解决潜在问题。