用途
该技能面向 Backstage 后端插件或模块的开发场景，帮助开发者在需要日志、配置、HTTP 路由、数据库、调度、缓存、URL 抓取、服务发现或认证等能力时，选择并正确使用对应的核心服务（core services）。当用户提到具体的 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（插件作用域，隔离 schema），参考 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”对应 database，“每 N 分钟轮询”对应 scheduler）。
适用场景
适用于 Backstage 后端插件或模块开发中需要接入核心服务的各类情况，包括添加依赖、选择服务、处理认证与跨插件调用、编写测试等。
限制与注意事项
技能列出了若干常见陷阱：
- 所有引用来自 @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(...)。并非每个服务都有 factory——httpRouter、cache、urlReader、lifecycle 通常由测试后端的默认值提供。
- 通过 discovery + auth 调用其他 Backstage 插件（跨插件 HTTP）时，对非 OK 响应使用 @backstage/errors 的 throw await ResponseError.fromResponse(response) 处理。它会解析响应体以获取结构化错误信息，并产生其他 Backstage 层（日志、错误上报、前端 <ResponseErrorPanel>）能理解的类型化错误。不要只抛 new Error(
Failed: ${response.status})。 - 在路由处理器内部，抛出 @backstage/errors 的类型化错误（NotFoundError、InputError、NotAllowedError、ConflictError、ServiceUnavailableError、ForwardedError 等）——默认后端错误中间件会将它们转换为格式正确的 HTTP 响应。错误情况不要使用 res.status(...).json(...)。参见 references/http-router.md。