路由与 API 分组

总览

ECShopX Java 对外 HTTP 路径统一以 /api/ 为业务 API 前缀（另有 /storage/、/wechatAuth/ 等，见架构说明）。本地默认基址：http://localhost:18080/api/。

路由分组由 Java 包路径 + @RequestMapping 共同表达：包名标识受众与版本，注解声明对外 URL。

管理端：`api/admin`

项	约定
包路径	`cn.shopex.ecshopx.<domain>.api.admin.v1`
典型前缀	`/api/v1/<资源域>`
鉴权	`@AdminAuth`、`@Activated` 等
示例类	`cn.shopex.ecshopx.goods.api.admin.v1.ItemsController`
示例路径	`@RequestMapping("/api/v1/goods")`

管理端面向 ecshopx-admin 等后台；路径中 v1 与包名 v1 对齐，便于后续并列 v2。

前台：`api/front`

项	约定
包路径	`cn.shopex.ecshopx.<domain>.api.front.v1`
典型前缀	`/api/v1/h5app/wxapp/...`（小程序 / H5 商城）
鉴权	`@FrontAuth`、`@FrontNoAuth`
示例类	`cn.shopex.ecshopx.goods.api.front.v1.ItemsController`
示例路径	`@RequestMapping("/api/v1/h5app/wxapp/goods")`

订单前台示例：cn.shopex.ecshopx.orders.api.front.v1.PaymentController → /api/v1/h5app/wxapp/trade。

开放 API：`openapi` / `thirdapi`

开放接口分两层理解：

1. 统一网关（对外签名入口）

模块：ecshopx-openapi
公共前缀：/api/openapi（OpenapiMethodRegistry.PUBLIC_OPENAPI_PREFIX）
网关控制器：cn.shopex.ecshopx.openapi.thirdapi.gateway.OpenapiGatewayController
按 openapi_list.csv 注册 method 名，经网关分发至 v1 / v2 内部实现

2. 版本化内部控制器与业务实现

版本	控制器包路径	内部路由前缀	业务实现位置
v1	`cn.shopex.ecshopx.openapi.thirdapi.v1`	`/api/openapi/internal/v1`	各 Bundle `openapi/*PortImpl`
v2	`cn.shopex.ecshopx.openapi.thirdapi.v2.<域>`	`/api/openapi/internal/v2`	各 Bundle `openapi/thirdapi/v2/*Service` + PortImpl

v1 示例

cn.shopex.ecshopx.openapi.thirdapi.v1.ItemController
@RequestMapping("/api/openapi/internal/v1")

v2 示例（控制器在 openapi 模块）

cn.shopex.ecshopx.openapi.thirdapi.v2.items.ItemController
@RequestMapping("/api/openapi/internal/v2")

v2 示例（商品域业务服务在 goods 模块）

cn.shopex.ecshopx.goods.openapi.thirdapi.v2.OpenapiThirdApiV2ItemStoreGetService

业务 Bundle 的 openapi 包命名约定：

openapi/ — Port 接口实现类（Openapi*PortImpl）
openapi/thirdapi/v2/ — v2 方法级业务服务（由 openapi 模块控制器或注册表转发调用）

说明：业务模块包内常见 openapi/thirdapi/v2；v1 控制器统一在 ecshopx-openapi 模块的 thirdapi.v1 包。对外仍通过 /api/openapi 网关按 version 路由。

路径前缀一览

用途	前缀	说明
业务 API	`/api/`	管理端、前台、内部接口均在其下
开放 API	`/api/openapi`	第三方签名调用入口
静态资源	`/storage/`	本地或 OSS 回源
微信回调	`/wechatAuth/`	授权与消息回调

Compose 本地访问表见技术说明与本地 / Docker 部署。

版本约定小结

URL 中的 v1：REST 资源 API 的主版本号（api/admin/v1、api/front/v1）。
OpenAPI v1 / v2：开放接口协议版本；内部路径 /api/openapi/internal/v1|v2，与网关 version 参数对应。
新增接口：优先在现有 v1 包下扩展；破坏性变更再评估 v2 包或新 OpenAPI 版本。

禁止事项

禁止	说明
在业务 Bundle 随意新增顶层路径，破坏 `/api/` 统一前缀	与前端约定保持一致
前台接口挂在 `api/admin` 或反之	分包与鉴权体系不同
开放 API 绕过 Port 直接调用他模块 Mapper	保持 openapi 与业务解耦
硬编码完整域名	使用相对路径或配置项

路由与 API 分组 ​

总览 ​

管理端：api/admin ​

前台：api/front ​

开放 API：openapi / thirdapi ​

1. 统一网关（对外签名入口） ​

2. 版本化内部控制器与业务实现 ​

路径前缀一览 ​

版本约定小结 ​

禁止事项 ​

相关章节 ​