衣拉客电商微服务项目搭建指南（初学者从 0 到 1 实战） 结合我们之前学习的 Nacos、Gateway、Feign、MyBatis 等组件，本文将以 “衣拉客电商系统” 为例，详细拆解微服务项目的完整搭建流程 —— 从需求分析、系统设计到工程落地，每个步骤都标注 “为什么这么做” 和 “易错点”，帮初学者建立 “微服务项目结构” 的清晰认知，避免盲目抄代码。
该项目内容来源于张hw老师，经过整理再创作
一、项目概述：先搞懂 “做什么” 和 “整体架构” 在搭框架前，我们先明确项目定位和整体结构，避免后续开发偏离方向。
1.1 项目需求：B2C 电商平台的核心模块 “衣拉客” 是全品类 B2C 电商系统，分网站前台（用户使用）和管理后台（管理员使用）两大模块：
模块核心功能网站前台首页展示、商品搜索、购物车、订单下单、用户中心（注册 / 登录 / 个人信息）管理后台商品管理（新增 / 编辑 / 上下架）、订单管理（发货 / 取消）、用户管理、权限控制以下是 B2C、C2C、B2B2C 模式的商家角色对比表
对比维度B2C（企业对消费者）C2C（消费者对消费者）B2B2C（企业对商家对消费者）模式核心企业直接卖给个人，无中间商家个人通过平台互相卖，平台仅搭框架平台整合第三方商家，一起卖给个人商家主体品牌 / 零售企业（如京东自营、苹果官网）个人 / 小微卖家（如闲鱼用户、淘宝个人店）第三方品牌 / 经销商（如天猫旗舰店、京东 POP 店）责任核心企业全担（品控、物流、售后直接负责）卖家自担（平台仅协助纠纷，不控品质）商家主担 + 平台监管（平台管规则、商家管履约）平台角色企业自身即平台（或用工具建平台）纯 “交易工具”（提供支付、搜索）纯 “生态管理者”（招商、定规则、分流量）典型案例京东自营、苹果官网、小米有品闲鱼、淘宝个人卖家、Poshmark天猫、京东 POP 模式、亚马逊第三方1.2 系统架构图：微服务的 “骨架” 整个系统基于 “微服务架构” 设计，按 “业务领域” 拆分服务，配合中间件实现高可用，架构图如下：
二、系统设计：搭框架前的 “设计决策” 设计阶段决定了后续开发的 “效率” 和 “可维护性”，核心关注数据库分库和技术选型。
2.1 数据库分库设计：按 “业务领域” 拆分 微服务架构中，数据库不能 “所有服务共用一个库”（否则回到单体架构），需按 “服务职责” 分库，避免跨库查询，提升性能和隔离性：
分库名称对应服务核心表zh_user用户服务（zh-user-service）t_user（用户基本信息）、t_user_address（收货地址）、t_login_record（登录记录）zh_goods商品服务（zh-goods-service）t_goods（商品基本信息）、t_category（商品分类）、t_stock（库存）zh_order订单服务（zh-order-service）t_order（订单主表）、t_order_item（订单明细）、t_cart（购物车）zh_system系统服务（zh-system-service）t_system_user（管理员信息）、t_role（角色）、t_menu（菜单权限）zh_business运营服务（zh-business-service）t_activity（促销活动）、t_news（新闻）、t_partner（合作伙伴）设计理由：
每个服务只操作自己的库，避免 “一个库挂了影响所有服务”；
后续扩展时，可单独对某个库做分表（如订单库数据多了分表），不影响其他库。
2.2 技术选型：“用什么工具” 和 “为什么用” 技术选型需结合 “项目需求” 和 “团队熟悉度”，本项目基于 Java 生态，核心技术栈如下（关联我们之前学的内容）：
技术领域选型作用（为什么用）主框架Spring Boot 2.7.5快速开发微服务，自动配置减少 XML微服务治理Spring Cloud Alibaba 2021.0.4.0包含 Nacos（注册 / 配置中心）、Sentinel（熔断降级），国内生态成熟服务注册 / 配置Nacos替代 Eureka+Config，一站式解决服务注册和配置管理，之前已详细学习服务网关Spring Cloud Gateway替代 Zuul，非阻塞性能好，统一入口路由、鉴权，之前已学习网关配置服务调用OpenFeign声明式 HTTP 调用，简化服务间通信，之前学过 Feign 整合 Sentinel数据访问MyBatis + MySQL关系型数据库访问，MyBatis 灵活适配复杂 SQL，之前学过 MyBatis 整合 Nacos 配置缓存Redis缓存高频数据（如商品详情、用户登录态），减轻数据库压力消息队列RabbitMQ异步处理（如订单下单后发消息通知库存）、秒杀削峰，之前已学习 RabbitMQ 消息模型搜索Elasticsearch商品全文搜索（如按名称 / 描述搜商品），比数据库模糊查询快前端技术前台：Thymeleaf；后台：Vue+ElementUI前台用模板引擎快速开发，后台用 Vue 实现动态交互安全框架Spring Security管理后台权限控制（登录验证、角色权限），下文会详细实战三、工程搭建：从 “父工程” 到 “子服务” 的完整步骤 微服务项目采用 “Maven 多模块” 结构，按 “父工程→子服务→Web 层” 的顺序搭建，确保依赖统一、结构清晰。
3.1 第一步：搭建父工程（zh_shop） 父工程的核心作用是统一管理依赖版本和抽取公共依赖，避免子服务依赖版本混乱。
3.1.1 操作步骤用 IDEA 新建 Maven 项目，GroupId 填com.zh，ArtifactId 填zh_shop，打包方式选pom；
删除父工程的src文件夹（父工程不写业务代码，只做依赖管理）；
配置pom.xml，核心是dependencyManagement（统一版本）和公共依赖。
3.1.2 父工程 pom.xml 详解
4.0.0
com.zh
zh_shop
1.0-SNAPSHOT
pom
17
17
UTF-8
2021.0.3
2021.0.4.0
2.7.5
org.springframework.boot
spring-boot-starter-parent
${spring-boot.version}
org.springframework.cloud
spring-cloud-dependencies
${spring-cloud.version}
pom
import
com.alibaba.cloud
spring-cloud-alibaba-dependencies
${spring-cloud-alibaba.version}
pom
import
org.springframework.boot
spring-boot-starter-web
com.alibaba.cloud
spring-cloud-starter-alibaba-nacos-config
org.springframework.cloud
spring-cloud-starter-bootstrap
org.apache.maven.plugins
maven-compiler-plugin
${maven.compiler.source}
${maven.compiler.target}
3.1.3 关键说明dependencyManagement vs dependencies：
dependencyManagement只 “声明版本”，不实际引入依赖；
dependencies会实际引入，且子服务会继承。
Bootstrap 依赖：之前学 Nacos 配置中心时强调过，必须加这个依赖，否则bootstrap.yml不生效，Nacos 配置拉取失败。
3.2 第二步：搭建子服务工程（核心微服务） 子服务按 “业务领域” 拆分，共 7 个核心服务，结构如下：
zh_shop（父工程）
├─ zh-common（公共模块：实体类、工具类）
├─ zh-user-service（用户服务）
├─ zh-goods-service（商品服务）
├─ zh-order-service（订单服务）
├─ zh-system-service（系统服务）
├─ zh-business-service（运营服务）
├─ zh-pay-service（支付服务）
└─ zh-gateway（网关服务）
3.2.1 先搭 “公共模块 zh-common”（所有服务都依赖）zh-common是 “工具库”，存放所有服务共用的代码，避免重复开发：
新建 Maven 子模块，ArtifactId 为zh-common；
核心内容：
实体类（如User、Goods、Order，对应数据库表）；
工具类（如Result统一响应类、日期工具、加密工具）；
公共依赖（如 FastJSON、Lombok）。
示例：统一响应类 Result.java（所有服务接口返回统一格式）：
package com.zh.common.entity;
import lombok.Data;
import java.util.List;
/**
* 统一响应类：所有接口返回此格式，前端好处理
*/
@Data
public class Result {
// 状态码：200=成功，401=权限不足，400=参数错误，500=系统错误
private Integer code;
// 提示信息
private String message;
// 单个数据（如详情接口）
private T data;
// 多个数据（如列表接口）
private List dataList;
// 成功静态方法（简化代码）
public static Result success() {
Result result = new Result<>();
result.setCode(200);
result.setMessage("SUCCESS");
return result;
}
public static Result success(T data) {
Result result = success();
result.setData(data);
return result;
}
// 失败静态方法
public static Result fail(Integer code, String message) {
Result result = new Result<>();
result.setCode(code);
result.setMessage(message);
return result;
}
}
注意：zh-common不需要application.yml和启动类，因为它不是独立运行的服务，只是依赖模块。
3.2.2 搭建 “业务服务”（以 zh-system-service 为例） 所有业务服务（用户、商品、订单等）的搭建流程一致，这里以 “系统服务（权限 / 菜单）” 为例：
步骤 1：新建子模块 父工程右键→New→Module→Maven，ArtifactId 为zh-system-service。
步骤 2：配置 pom.xml（引入依赖）
com.zh
zh_shop
1.0-SNAPSHOT
4.0.0
zh-system-service
com.alibaba.cloud
spring-cloud-starter-alibaba-nacos-discovery
com.zh
zh-common
1.0-SNAPSHOT
org.mybatis.spring.boot
mybatis-spring-boot-starter
2.1.3
mysql
mysql-connector-java
runtime
com.github.pagehelper
pagehelper
4.1.3
步骤 3：配置 application.yml（服务端口、Nacos、数据库）
server:
port: 8006 # 系统服务端口，确保不与其他服务冲突（如用户服务8001，商品服务8002）
spring:
application:
name: system-service # 服务名，注册到Nacos的标识，必须无下划线
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848 # Nacos地址，和其他服务一致
service: ${spring.application.name}
# 数据库配置（系统库zh_system）
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost:3306/zh_system?useSSL=false&serverTimezone=UTC
username: root
password: root
# MyBatis配置
mybatis:
mapper-locations: classpath:mybatis/mapper/*.xml # Mapper.xml文件路径
type-aliases-package: com.zh.system.entity # 实体类包名，简化XML中的类名
步骤 4：编写启动类（开启服务注册和 MyBatis 扫描）
package com.zh.system;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
@SpringBootApplication
@EnableDiscoveryClient // 开启服务注册发现，注册到Nacos
@MapperScan("com.zh.system.mapper") // 扫描MyBatis的Mapper接口
public class SystemServiceApplication {
public static void main(String[] args) {
SpringApplication.run(SystemServiceApplication.class, args);
}
}
步骤 5：编写核心业务代码（以 “用户登录查询” 为例）实体类（com.zh.system.entity.SystemUser）：对应zh_system库的t_system_user表；
Mapper 接口（com.zh.system.mapper.SystemUserMapper）：数据库操作；
package com.zh.system.mapper;
import com.zh.system.entity.SystemUser;
import org.apache.ibatis.annotations.Select;
public interface SystemUserMapper {
// 根据用户名查询管理员信息
@Select("select * from t_system_user where suname = #{username}")
SystemUser selectByUsername(String username);
}
Service 层（com.zh.system.service.SystemUserService）：业务逻辑；
package com.zh.system.service;
import com.zh.system.entity.SystemUser;
import com.zh.system.mapper.SystemUserMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class SystemUserService {
@Autowired
private SystemUserMapper systemUserMapper;
// 根据用户名查询用户
public SystemUser getByUsername(String username) {
return systemUserMapper.selectByUsername(username);
}
}
Controller 层（com.zh.system.controller.SystemUserController）：对外提供接口；
package com.zh.system.controller;
import com.zh.common.entity.Result;
import com.zh.system.entity.SystemUser;
import com.zh.system.service.SystemUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/system/user")
public class SystemUserController {
@Autowired
private SystemUserService systemUserService;
// 提供给管理后台调用：根据用户名查询管理员
@RequestMapping("/getByUsername")
public Result getByUsername(@RequestParam String username) {
SystemUser user = systemUserService.getByUsername(username);
if (user == null) {
return Result.fail(400, "用户名不存在");
}
return Result.success(user);
}
}
3.2.3 搭建 “网关服务 zh-gateway”（特殊配置） 网关是所有请求的入口，配置和普通服务不同，需注意 “排除 Web 依赖”（Gateway 基于 WebFlux，和 MVC 冲突）：
步骤 1：新建子模块 zh-gateway，配置 pom.xml
com.zh
zh_shop
1.0-SNAPSHOT
4.0.0
zh-gateway
org.springframework.cloud
spring-cloud-starter-gateway
com.alibaba.cloud
spring-cloud-starter-alibaba-nacos-discovery
org.springframework.cloud
spring-cloud-starter-loadbalancer
org.springframework.boot
spring-boot-starter-web
*
*
步骤 2：配置 application.yml（网关路由）
server:
port: 8080 # 网关端口，对外暴露的统一入口
spring:
application:
name: zh-gateway
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848
# Gateway核心配置：路由规则
gateway:
discovery:
locator:
enabled: true # 开启“服务名路由”：http://网关地址/服务名/接口路径
# 自定义路由规则（可选，比服务名路由更灵活）
routes:
# 路由1：管理后台→系统服务
- id: route-system # 路由唯一ID
uri: lb://system-service # 转发到system-service，lb=负载均衡
predicates:
- Path=/system/** # 匹配路径：/system开头的请求
filters:
- StripPrefix=1 # 去掉路径前缀：/system/user/getByUsername → /user/getByUsername
# 路由2：前台→商品服务
- id: route-goods
uri: lb://goods-service
predicates:
- Path=/goods/**
filters:
- StripPrefix=1
步骤 3：启动类
package com.zh.gateway;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
public static void main(String[] args) {
SpringApplication.run(GatewayApplication.class, args);
}
}
测试网关：启动 Gateway 和 SystemService 后，访问http://localhost:8080/system/user/getByUsername?username=admin，会转发到system-service的/user/getByUsername接口，返回管理员信息。
3.3 第三步：搭建 Web 层工程（前台 + 后台） Web 层是 “用户直接访问的界面层”，分前台（用户用）和后台（管理员用），负责 “页面展示” 和 “调用微服务接口”。
3.3.1 管理后台（zh-web-manage，Vue+ElementUI） 后台是管理员操作的界面，用 Vue+ElementUI 开发，核心是 “调用微服务接口” 和 “权限控制”。
步骤 1：新建 Maven 子模块 zh-web-manage，配置 pom.xml
com.zh
zh_shop
1.0-SNAPSHOT
4.0.0
zh-web-manage
com.alibaba.cloud
spring-cloud-starter-alibaba-nacos-discovery
org.springframework.cloud
spring-cloud-starter-openfeign
org.springframework.boot
spring-boot-starter-security
org.springframework.boot
spring-boot-starter-thymeleaf
com.zh
zh-common
1.0-SNAPSHOT
步骤 2：核心功能：Spring Security 登录权限（重点） 后台需要 “管理员登录验证” 和 “角色权限控制”，这里以 “登录功能” 为例：
Feign 接口（调用系统服务）：
package com.zh.manage.feign;
import com.zh.common.entity.Result;
import com.zh.system.entity.SystemUser;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
// 调用system-service服务
@FeignClient(name = "system-service", contextId = "systemUserFeign")
public interface SystemUserFeign {
// 对应system-service的/system/user/getByUsername接口
@RequestMapping("/system/user/getByUsername")
Result getByUsername(@RequestParam String username);
}
自定义 UserDetailsService（登录验证逻辑）：
package com.zh.manage.security;
import com.zh.common.entity.Result;
import com.zh.manage.feign.SystemUserFeign;
import com.zh.system.entity.SystemUser;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.authority.AuthorityUtils;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Component;
@Component
public class MyUserDetailsService implements UserDetailsService {
@Autowired
private SystemUserFeign systemUserFeign;
@Autowired
private PasswordEncoder passwordEncoder;
// 登录时自动调用：根据用户名查询用户
@Override
public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
// 1. 调用系统服务查询用户
Result result = systemUserFeign.getByUsername(username);
SystemUser user = result.getData();
if (user == null) {
throw new UsernameNotFoundException("用户名不存在");
}
// 2. 构建权限列表（后续从系统服务获取角色权限）
String authorities = "ROLE_ADMIN"; // 临时给管理员权限
// 3. 返回Spring Security需要的User对象（密码需加密）
return new User(
user.getSuname(),
passwordEncoder.encode(user.getSupwd()), // 密码加密（数据库密码应存加密后的值）
AuthorityUtils.commaSeparatedStringToAuthorityList(authorities)
);
}
}
Spring Security 配置类：
package com.zh.manage.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
// 密码加密器（必须配置，否则登录报错）
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
// 配置拦截规则和登录页面
@Override
protected void configure(HttpSecurity http) throws Exception {
http.authorizeRequests()
.antMatchers("/login.html", "/css/**", "/js/**").permitAll() // 静态资源和登录页不用认证
.anyRequest().authenticated() // 其他请求必须登录
.and()
.formLogin()
.loginPage("/login.html") // 自定义登录页
.loginProcessingUrl("/login") // 登录请求路径（表单action="login"）
.defaultSuccessUrl("/main.html") // 登录成功跳转页
.permitAll()
.and()
.csrf().disable(); // 关闭CSRF（开发阶段方便测试）
}
}
登录页面（放在resources/templates/login.html）：
管理后台登录
登录
3.3.2 网站前台（zh-web-front，Thymeleaf） 前台是用户访问的界面，用 Thymeleaf 模板引擎开发，核心是 “调用商品、订单服务” 展示数据，搭建流程和后台类似，重点是 “页面渲染” 和 “用户交互”（如商品列表、加入购物车）。
四、跨服务实体类调用：避免重复定义 微服务中，多个服务可能用到同一个实体类（如User在用户服务和订单服务都需要），此时不能每个服务都定义一次，需通过 “依赖公共模块” 或 “依赖其他服务” 实现共享。
4.1 方案 1：通过公共模块共享（推荐） 将实体类放在zh-common中，所有服务依赖zh-common，这是最规范的方式：
在zh-common的com.zh.common.entity包下定义User类；
其他服务（如订单服务）引入zh-common依赖，直接 import 使用：
import com.zh.common.entity.User; // 从公共模块导入
4.2 方案 2：依赖其他服务（特殊场景） 若实体类只在两个服务间共享，且不想放公共模块，可直接依赖对方服务（不推荐，耦合度高）：
在用户服务（zh-user-service）中定义User类；
在订单服务（zh-order-service）的 pom.xml 中引入用户服务依赖：
com.zh
zh-user-service
1.0-SNAPSHOT
订单服务中直接使用User类：
import com.zh.user.entity.User; // 从用户服务导入
注意：方案 2 会导致 “订单服务依赖用户服务”，若用户服务修改User类，订单服务可能报错，优先用方案 1。
五、项目启动与验证：确保整个链路通 搭建完成后，按以下顺序启动服务，验证是否正常运行：
启动 Nacos Server（startup.cmd -m standalone）；
启动所有微服务（用户、商品、订单、系统、网关）；
启动 Web 层（后台、前台）；
验证：
访问 Nacos 控制台（http://localhost:8848/nacos），查看所有服务是否注册成功；
访问网关地址（http://localhost:8080），测试后台登录和接口调用。
六、初学者重点 & 易错点总结依赖冲突：
Gateway 必须排除spring-boot-starter-web，否则和 WebFlux 冲突；
所有服务的 Spring Boot、Spring Cloud 版本必须兼容（父工程统一管理）。
Nacos 相关：
服务名不能有下划线，否则 Gateway 路由和负载均衡会报错；
必须加spring-cloud-starter-bootstrap，否则bootstrap.yml不生效。
MyBatis 相关：
启动类必须加@MapperScan，否则 Mapper 接口无法扫描；
mapper-locations路径必须正确，否则找不到 Mapper.xml。
权限控制：
Spring Security 必须配置PasswordEncoder，否则登录时密码无法匹配；
静态资源必须配置permitAll，否则登录页样式加载失败。
七、后续扩展方向集成 Sentinel：给核心接口（如下单、支付）加熔断降级，避免故障扩散；
集成 RabbitMQ：实现订单异步处理（如下单后发消息通知库存服务）；
集成 Redis：缓存商品详情和用户登录态，减轻数据库压力；
前端优化：后台用 Vue CLI 构建，前台用 Vue 实现单页应用（SPA）。
通过本案例，希望你能理解微服务项目的 “分层思想” 和 “依赖管理”，后续开发时能按 “业务拆分服务、公共代码抽模块” 的思路，搭建可维护、可扩展的微服务框架。