Appearance

快速入门 ​

本文以 ecshopx-goods（商品域） 为例，走通一条典型后端改动路径：启动环境 → 读代码 → 改表迁移 → Service / Controller → 调 API 验证。不虚构「从零脚手架新模块」为唯一入口；新增模块见文末检查清单与 Bundle。

默认 API 基址：http://localhost:18080/api/（Compose 或本地 local profile）。

1. 启动环境 ​

方式 A：Docker Compose（推荐） ​

bash
cd ecshopx-java
docker compose up -d              # 首次会构建镜像 + 导入 SQL，耗时 5~15 分钟
docker compose logs -f ecshopx-java

启动后 API 基址：http://localhost:18080/api/（见 本地 / Docker 部署 访问地址表）。

方式 B：本地 Maven + local profile ​

需自备 MySQL / Redis（或复用 Compose 只起中间件）。在 ecshopx-java 目录：

bash
./mvnw -pl ecshopx-bootstrap -am spring-boot:run \
  -Dspring-boot.run.profiles=local

本地配置样例：ecshopx-bootstrap/src/main/resources/application-local.properties。

2. 选定改动点：商品列表（只读走查） ​

以管理端商品列表为故事线，涉及类：

层级类 / 路径
Controllerecshopx-goods/.../api/admin/v1/ItemsController.java
Serviceecshopx-goods/.../service/items/GoodsItemsListFacadeService.java
Repository（可选）ecshopx-goods/.../repository/ItemsRepository.java
Mapperecshopx-goods/.../mapper/ItemsMapper.java
Domainecshopx-goods/.../domain/Items.java → 表 items

ItemsController 映射前缀为 @RequestMapping("/api/v1/goods")，列表接口：

java
@GetMapping(value = "/items", name = "商品列表")
public ResponseEntity<ApiResult<Map<String, Object>>> getItemsList(HttpServletRequest request)

完整 URL：GET http://localhost:18080/api/v1/goods/items（需管理端 JWT，见 @AdminAuth）。

3. 假设加字段：Domain → 迁移 → Review → Migrate ​

假设要在 items 表增加备注列 internal_note，供后台列表筛选（示例字段，提交前请按业务评审）。

3.1 修改 Domain ​

在 Items.java 增加：

java
@MpField(value = "internal_note", columnType = "string", length = 255, nullable = true, comment = "内部备注")
private String internalNote;

3.2 生成迁移 ​

bash
cd ecshopx-java
bin/make-migration add_items_internal_note

Review 生成文件，例如：

text
ecshopx-bootstrap/src/main/resources/db/migration/VyyyyMMddHHmmss__add_items_internal_note.sql

确认列类型、NULL、默认值、注释与索引是否符合预期（详见 数据库快速入门）。

3.3 执行迁移 ​

bash
bin/make-migration migrate
# 或
bin/make-migration migrate --profile local

spring.flyway.enabled=false：迁移与 spring-boot:run 解耦，避免启动时误改库。

4. Service → Controller ​

  1. Service：在 GoodsItemsListFacadeService（或对应查询封装）中读取 internalNote，按需加入列表 DTO / 查询条件。
  2. Controller：若仅扩展现有列表返回字段，通常不必新增路由；若新增独立接口，在 ItemsController 同包按 路由约定 添加方法。

跨模块数据请走 Port，勿直接引用其他 Bundle 的 Mapper（见 Bundle）。

5. 验证 API ​

应用监听 18080 后，用 curl 探测（管理端接口需有效 Operator JWT）：

bash
# 商品列表（管理端）
curl -sS -H "Authorization: Bearer <operator_jwt>" \
  "http://localhost:18080/api/v1/goods/items?page=1&page_size=10"

# 商品详情（管理端，路径同样来自 ItemsController）
curl -sS -H "Authorization: Bearer <operator_jwt>" \
  "http://localhost:18080/api/v1/goods/items/12345"

C 端小程序路径示例（api/front/v1/ItemsController，前缀 /api/v1/h5app/wxapp/goods）：

bash
curl -sS "http://localhost:18080/api/v1/h5app/wxapp/goods/items?page=1&page_size=10"

本地演示账号：admin / Shopex123（见 本地 / Docker 部署）。

6. 新增业务模块检查清单 ​

与 Bundle 保持一致，新增 ecshopx-<domain> 时核对：

  • [ ] 父工程 pom.xml <modules> 增加 ecshopx-<domain>
  • [ ] ecshopx-bom（或父 POM dependencyManagement）登记模块坐标
  • [ ] ecshopx-bootstrap/pom.xml 增加对 ecshopx-<domain> 的依赖
  • [ ] 根包命名为 cn.shopex.ecshopx.<domain>
  • [ ] 建立 api / service / mapper / domain 等目录
  • [ ] 跨模块能力先定义 Port，再在 integration 实现
  • [ ] 若有定时任务，在 cron 包声明 @XxlJob
  • [ ] Flyway 迁移放在 ecshopx-bootstrap/src/main/resources/db/migration

相关章节 ​