using-backstage-backend-services

Backstage 后端服务

何时使用此技能

• 插件或模块需要日志记录、配置、HTTP 路由、数据库、调度、缓存、URL 获取、服务发现或身份验证
• 用户提及任何特定的 coreServices.* 引用
• 在 register({ deps: {...} }) 代码块中添加新的依赖

选择合适的服务

需求	服务	参考文档
日志记录	coreServices.logger（限定于插件作用域，并预先标记 pluginId）	references/logger-and-config.md
读取 app-config.yaml	coreServices.rootConfig	references/logger-and-config.md
注册 HTTP 路由	coreServices.httpRouter	references/http-router.md
Knex 数据库访问	coreServices.database（限定于插件作用域，使用隔离的架构）	references/database.md
定期任务 / cron 任务	coreServices.scheduler	references/scheduler-and-lifecycle.md
启动 / 关闭钩子	coreServices.lifecycle（插件）或 coreServices.rootLifecycle（根级）	references/scheduler-and-lifecycle.md
服务间令牌	coreServices.auth	references/auth.md
验证传入的请求	coreServices.httpAuth	references/auth.md
根据凭据解析当前用户	coreServices.userInfo	references/auth.md
读取外部 URL（GitHub、GitLab 等）	coreServices.urlReader	references/urlReader-and-discovery.md
解析后端插件的基础 URL	coreServices.discovery	references/urlReader-and-discovery.md
键值缓存	coreServices.cache	references/cache.md

两种调用模式

• 独立模式：为现有插件或模块添加服务依赖。
• 脚手架后（由 creating-backstage-plugin 为后端模板调用）：将 coreServices.logger 和 coreServices.httpRouter 设为默认服务；如果意图表明需要其他服务，则提供这些服务（例如，“存储 X” → 数据库；“每 N 分钟轮询一次” → 调度器）。

常见注意事项

• 所有引用均来自 @backstage/backend-plugin-api。实际实现来自 @backstage/backend-defaults，但插件只会使用这些引用。
• 插件级服务会为每个插件提供独立实例——coreServices.database 返回一个作用于每个插件专属 schema 的 Knex 客户端；coreServices.logger 会预先标记 pluginId。不要通过传递 Knex 实例来尝试在插件之间共享它——请改用 coreServices.discovery + HTTP 进行跨插件调用。
• auth、httpAuth 和 userInfo 服务很容易混淆。auth 为服务间调用签发／验证令牌；httpAuth 对传入的 Express 请求进行身份验证；userInfo 则根据 httpAuth 返回的凭据解析用户身份。
• coreServices.scheduler 可跨副本调度持久化任务——不要在生产任务中使用 setInterval。
• 对于测试：使用 mockServices.<name>(...) 获取用于单元测试的实例；将服务传递给 startTestBackend({ features: [...] }) 时，使用 mockServices.<name>.factory(...)。并非每项服务都有工厂——测试后端的默认配置通常会提供 httpRouter、cache、urlReader 和 lifecycle。
• 通过 discovery + auth 调用另一个 Backstage 插件（跨插件 HTTP）时，遇到非 OK 响应应使用 throw await ResponseError.fromResponse(response)，该方法来自 @backstage/errors。它会解析响应正文中的结构化错误信息，并生成 Backstage 的其他层（日志记录、错误报告、前端 <ResponseErrorPanel>）能够识别的类型化错误。切勿只使用 throw new Error(\Failed: ${response.status}`)`。
• 在路由处理程序中，抛出来自 @backstage/errors 的类型化错误（NotFoundError、InputError、NotAllowedError、ConflictError、ServiceUnavailableError、ForwardedError 等）——默认后端错误中间件会将其转换为格式正确的 HTTP 响应。对于错误情况，不要使用 res.status(...).json(...)。请参阅 references/http-router.md。