跳到主要内容

[草稿] 网关与接口文档聚合

Nebula 微服务模式下，最值得前端和联调人员优先接入的不是某一个业务服务，而是 nebula-gateway-service。因为它同时解决了两个问题：统一入口和统一文档。

网关做了什么​

从当前配置可以直接看出，网关已经代理了这些标准路径：

  • /api/auth/**
  • /api/dict/**
  • /api/param/**
  • /api/notify/**
  • /api/comms/**
  • /api/storage/**
  • /api/scheduler/**

这意味着前端只需要认一个基础地址，而不需要记住多个服务端口。

文档为什么也要走网关​

nebula-gateway-service 不只是转发业务接口，还聚合了各服务的 OpenAPI 文档。当前最常用的入口是：

  • http://localhost:17777/doc.html
  • http://localhost:17777/swagger-ui.html

这对前端、测试、实施都很重要，因为大家不需要分别打开多个服务的文档地址。

这里的 17777 和各下游服务地址，都是当前仓库配置中的默认值。实际部署时可以通过网关配置覆盖，不应把这些端口当成所有环境中的固定常量。

最适合什么场景​

前端联调​

前端可以直接把请求统一指向网关，减少环境切换成本。

测试联调​

测试可以从一个文档入口快速检查所有服务的接口契约。

后端新增服务接入​

如果后续新增服务，也应同步补充网关路由和文档聚合配置，否则虽然服务能访问，但整体协作体验会变差。

一个简单的使用原则​

只要你进入了“多个服务一起跑”的阶段，就尽量让人和系统都优先面向网关，而不是面向单个服务地址。这样前端环境、接口文档和运维暴露方式都会更统一。