整合CRUD：從Nacos注冊(cè)到OpenFeign調(diào)用的完整實(shí)踐)
1. 為什么這個(gè)系列的第一篇要寫(xiě)CRUD微服務(wù)落地的第一塊敲門(mén)磚先說(shuō)一個(gè)很多人容易誤解的點(diǎn)Spring Cloud 是個(gè)宏觀的微服務(wù)治理方案名字里帶個(gè)云字但實(shí)際上它解決的不是業(yè)務(wù)代碼怎么寫(xiě)而是多個(gè)服務(wù)進(jìn)程之間怎么組織、怎么發(fā)現(xiàn)、怎么通信、怎么容錯(cuò)。CRUD 則是任何業(yè)務(wù)系統(tǒng)里最基礎(chǔ)、也最繞不開(kāi)的數(shù)據(jù)操作能力。把 Spring Cloud 和 CRUD 放到一起整合本質(zhì)上是做這樣一件事讓一個(gè)業(yè)務(wù)模塊以微服務(wù)的方式跑起來(lái)并且通過(guò)注冊(cè)中心、網(wǎng)關(guān)、服務(wù)調(diào)用這些 Spring Cloud 核心組件完成完整的請(qǐng)求鏈路。我自己的體會(huì)是網(wǎng)上一搜 Spring Cloud鋪天蓋地都是注冊(cè)中心原理網(wǎng)關(guān)過(guò)濾器分布式事務(wù)這些偏治理側(cè)的內(nèi)容反而很少有人把一個(gè)最簡(jiǎn)單的用戶(hù)模塊從數(shù)據(jù)庫(kù)到前端接口完整走通微服務(wù)調(diào)用鏈這件事講清楚。但實(shí)際項(xiàng)目落地的時(shí)候你第一步需要的就是一個(gè)能跑通的 CRUD 服務(wù)因?yàn)樗逆溌纷疃?、?wèn)題最直觀、也最適合用來(lái)驗(yàn)證整套基礎(chǔ)設(shè)施是否正常。這篇文章定位為Spring Cloud 整合一適合兩類(lèi)人一類(lèi)是剛接觸微服務(wù)、想搭一套本地可運(yùn)行 Demo 的開(kāi)發(fā)者另一類(lèi)是已經(jīng)用單體寫(xiě)過(guò)很多 CRUD、想看看同一套業(yè)務(wù)代碼放到微服務(wù)架構(gòu)里會(huì)發(fā)生什么變化的同學(xué)。文章里我會(huì)把選型理由、配置細(xì)節(jié)、啟動(dòng)順序、踩坑記錄一次講透保證你照著做能跑起來(lái)而不是看了一堆抽象概念。整體架構(gòu)我會(huì)控制在三個(gè)服務(wù)內(nèi)一個(gè)用于演示 CRUD 的user-service一個(gè)負(fù)責(zé)轉(zhuǎn)發(fā)請(qǐng)求的網(wǎng)關(guān)服務(wù)gateway-service再加上注冊(cè)中心 Nacos。后文還會(huì)引入 OpenFeign 演示服務(wù)間調(diào)用這也是微服務(wù)場(chǎng)景下最典型的用法。2. 版本選型與父工程搭建這一步?jīng)Q定后面三個(gè)月是否順利2.1 Spring Cloud 與 Spring Boot 的版本對(duì)應(yīng)關(guān)系Spring Cloud 的版本號(hào)經(jīng)歷了一次重要變化。早期用Dalston、Edgware、Hoxton這類(lèi)倫敦地鐵站名來(lái)命名從2020.0開(kāi)始改成了年份命名方式。很多新手在這里第一個(gè)坑就是Spring Cloud 和 Spring Boot 必須嚴(yán)格匹配否則啟動(dòng)時(shí)會(huì)報(bào)各種莫名其妙的 NoClassDefFoundError 或者 Bean 創(chuàng)建異常。我這里直接給出兩套經(jīng)過(guò)驗(yàn)證的穩(wěn)定組合你可以按自己的 JDK 情況選組合JDKSpring BootSpring CloudSpring Cloud Alibaba傳統(tǒng)穩(wěn)定組合8/112.7.182021.0.82021.0.5.0新版組合173.2.x2023.0.x2023.0.1.0我個(gè)人建議如果是為了學(xué)習(xí)和本地驗(yàn)證優(yōu)先選第一套JDK 8 Spring Boot 2.7.18 Spring Cloud 2021.0.8。原因很現(xiàn)實(shí)這套組合的網(wǎng)上資料最多遇到問(wèn)題一搜就有答案而且 Nacos、Gateway、OpenFeign 這些組件的兼容性都已經(jīng)被大量生產(chǎn)項(xiàng)目驗(yàn)證過(guò)了。Spring Boot 3.x 雖然新但 Jakarta EE 的包名遷移、Spring Security 6 的配置變化對(duì)初學(xué)者來(lái)說(shuō)排查成本偏高。2.2 父 POM 的依賴(lài)管理我會(huì)創(chuàng)建一個(gè) Maven 父工程只放依賴(lài)管理和公共屬性不寫(xiě)業(yè)務(wù)代碼。這樣做的好處是子模塊之間版本統(tǒng)一后續(xù)引入新的微服務(wù)模塊時(shí)不需要再重復(fù)指定版本號(hào)。父 POM 的核心內(nèi)容如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent properties spring-cloud.version2021.0.8/spring-cloud.version spring-cloud-alibaba.version2021.0.5.0/spring-cloud-alibaba.version mybatis-plus.version3.5.3.2/mybatis-plus.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version${spring-cloud-alibaba.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意dependencyManagement里的import方式。它不像普通依賴(lài)那樣把 jar 直接引入而是把對(duì)應(yīng) BOM 里的版本管理信息導(dǎo)入當(dāng)前 POM。這樣你在子模塊里寫(xiě)依賴(lài)的時(shí)候可以不加versionMaven 會(huì)自動(dòng)找父工程里鎖定的版本。2.3 子模塊的拆分方式父工程下我會(huì)建兩個(gè)子模塊分別對(duì)應(yīng)兩個(gè)可啟動(dòng)的服務(wù)spring-cloud-crud-demo ├── pom.xml # 父工程 ├── gateway-service/ # 網(wǎng)關(guān)服務(wù) └── user-service/ # 用戶(hù)服務(wù)承載 CRUD 業(yè)務(wù)嚴(yán)格來(lái)說(shuō)網(wǎng)關(guān)也是微服務(wù)的一個(gè)成員所以它也要注冊(cè)到 Nacos只是它的職責(zé)不是處理業(yè)務(wù)而是做路由轉(zhuǎn)發(fā)。兩個(gè)子模塊的pom.xml里只需聲明自身需要的依賴(lài)即可。user-service的依賴(lài)如下dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version${mybatis-plus.version}/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency /dependenciesgateway-service的依賴(lài)則要注意不要加spring-boot-starter-web。這一點(diǎn)我在后面會(huì)專(zhuān)門(mén)講Gateway 基于 WebFlux 響應(yīng)式模型和傳統(tǒng)的 Servlet Web 容器沖突加了就啟動(dòng)報(bào)錯(cuò)。3. 注冊(cè)中心接入用 Nacos 讓服務(wù)先彼此看見(jiàn)3.1 為什么選擇 Nacos 而不是 EurekaEureka 2.x 已經(jīng)停止維護(hù)這已經(jīng)是共識(shí)。Nacos 是阿里巴巴開(kāi)源的服務(wù)發(fā)現(xiàn)與配置管理組件目前在國(guó)內(nèi)微服務(wù)項(xiàng)目中占絕對(duì)主流。選它的理由很簡(jiǎn)單既能做服務(wù)注冊(cè)發(fā)現(xiàn)又能做配置中心一套組件解決兩個(gè)問(wèn)題而且和 Spring Cloud Alibaba 生態(tài)結(jié)合得非常順滑。后文如果繼續(xù)寫(xiě)這個(gè)系列配置中心的整合就會(huì)直接基于 Nacos不需要額外引入新組件。3.2 本地啟動(dòng) Nacos ServerNacos Server 的啟動(dòng)方式有源碼編譯、Docker、下載發(fā)行包三種。對(duì)于本地驗(yàn)證我推薦直接下載最新穩(wěn)定版發(fā)行包# 解壓后進(jìn)入 bin 目錄Linux/macOS 執(zhí)行 sh startup.sh -m standalone # Windows 執(zhí)行 startup.cmd -m standalonestandalone參數(shù)表示單機(jī)模式Nacos 默認(rèn)使用內(nèi)置的 Derby 數(shù)據(jù)庫(kù)存儲(chǔ)服務(wù)實(shí)例信息不需要額外安裝數(shù)據(jù)庫(kù)。啟動(dòng)成功后訪(fǎng)問(wèn)http://127.0.0.1:8848/nacos默認(rèn)用戶(hù)名密碼都是nacos能看到控制臺(tái)界面就說(shuō)明注冊(cè)中心已經(jīng)就緒。3.3 user-service 接入 Nacosuser-service的application.yml中配置如下server: port: 8081 spring: application: name: user-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: public group: DEFAULT_GROUP datasource: url: jdbc:mysql://127.0.0.1:3306/crud_demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto幾個(gè)關(guān)鍵點(diǎn)解釋一下spring.application.name是服務(wù)在注冊(cè)中心里的唯一標(biāo)識(shí)也是后面服務(wù)間調(diào)用和網(wǎng)關(guān)路由的關(guān)鍵依據(jù)。名字別亂起建議用中劃線(xiàn)分隔比如user-service而不是userService。namespace和group可以在沒(méi)有顯式配置時(shí)省略默認(rèn)就是public和DEFAULT_GROUP。但我在實(shí)際項(xiàng)目里建議一開(kāi)始就顯式寫(xiě)出來(lái)因?yàn)楹罄m(xù)做環(huán)境隔離dev/test/prod 各占一個(gè) namespace時(shí)你會(huì)理解這兩個(gè)參數(shù)的意義。3.4 啟動(dòng)類(lèi)上加注解在UserServiceApplication上加上EnableDiscoveryClientSpringBootApplication EnableDiscoveryClient public class UserServiceApplication { public static void main(String[] args) { SpringApplication.run(UserServiceApplication.class, args); } }在 Spring Cloud 2021.x 版本里注冊(cè)發(fā)現(xiàn)能力已經(jīng)默認(rèn)開(kāi)啟不加這個(gè)注解也能注冊(cè)但我建議保留。原因有兩個(gè)一是顯式表明這個(gè)服務(wù)要參與服務(wù)發(fā)現(xiàn)二是如果你做一些自定義的注冊(cè)邏輯或者需要注入 DiscoveryClient 對(duì)象時(shí)這個(gè)注解會(huì)讓代碼意圖更清晰。啟動(dòng)user-service后回到 Nacos 控制臺(tái)服務(wù)列表里應(yīng)該能看到user-service已經(jīng)注冊(cè)上來(lái)狀態(tài)為健康。4. CRUD 三件套的實(shí)現(xiàn)實(shí)體、持久層、接口層微服務(wù)架構(gòu)下的業(yè)務(wù)代碼寫(xiě)法其實(shí)和單體項(xiàng)目沒(méi)有本質(zhì)區(qū)別。這也是我特別想強(qiáng)調(diào)的一點(diǎn)Spring Cloud 的整合重點(diǎn)在基礎(chǔ)設(shè)施和通信鏈路而不是讓你把熟悉的 CRUD 寫(xiě)法推翻重來(lái)。4.1 數(shù)據(jù)庫(kù)準(zhǔn)備先準(zhǔn)備一張簡(jiǎn)單的用戶(hù)表CREATE DATABASE IF NOT EXISTS crud_demo DEFAULT CHARACTER SET utf8mb4; USE crud_demo; CREATE TABLE user ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT 主鍵ID, username VARCHAR(64) NOT NULL COMMENT 用戶(hù)名, email VARCHAR(128) DEFAULT NULL COMMENT 郵箱, phone VARCHAR(20) DEFAULT NULL COMMENT 手機(jī)號(hào), created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新時(shí)間, PRIMARY KEY (id) ) ENGINE InnoDB DEFAULT CHARSET utf8mb4 COMMENT 用戶(hù)表;這里有個(gè)字段命名的小細(xì)節(jié)數(shù)據(jù)庫(kù)字段用下劃線(xiàn)風(fēng)格created_atJava 實(shí)體用駝峰風(fēng)格createdAt。MyBatis-Plus 的map-underscore-to-camel-case配置會(huì)自動(dòng)做映射省去大量手寫(xiě) ResultMap 的工作。我在 3.3 里的配置已經(jīng)打開(kāi)了這個(gè)開(kāi)關(guān)。4.2 實(shí)體類(lèi)與 Mapper實(shí)體類(lèi)對(duì)應(yīng)表結(jié)構(gòu)Data TableName(user) public class User { TableId(type IdType.AUTO) private Long id; private String username; private String email; private String phone; private LocalDateTime createdAt; private LocalDateTime updatedAt; }TableName(user)注解是因?yàn)閡ser這個(gè)表名不是 Java 命名規(guī)范的駝峰形式如果不注解MyBatis-Plus 會(huì)默認(rèn)映射到user實(shí)體類(lèi)名正好也能對(duì)上但為了保險(xiǎn)起見(jiàn)還是顯式標(biāo)注。Mapper 接口更簡(jiǎn)單Mapper public interface UserMapper extends BaseMapperUser { }BaseMapperT是 MyBatis-Plus 提供的通用 CRUD Mapper內(nèi)置了selectById、insert、updateById、deleteById、selectList等方法。正常情況下你不需要寫(xiě)任何 XML 映射文件也不需要寫(xiě) SQL 語(yǔ)句。這套寫(xiě)法的好處是一個(gè)實(shí)體對(duì)應(yīng)一個(gè) MapperCRUD 的基礎(chǔ)方法全部開(kāi)箱即用。4.3 Service 層的接口與實(shí)現(xiàn)Service 層建議按接口 實(shí)現(xiàn)類(lèi)的模式拆開(kāi)雖然代碼量多一些但在業(yè)務(wù)復(fù)雜后你會(huì)受益于這種隔離public interface UserService { User getUserById(Long id); Long createUser(User user); Boolean updateUser(User user); Boolean deleteUser(Long id); ListUser listUsers(); } Service RequiredArgsConstructor public class UserServiceImpl implements UserService { private final UserMapper userMapper; Override public User getUserById(Long id) { return userMapper.selectById(id); } Override public Long createUser(User user) { user.setCreatedAt(LocalDateTime.now()); user.setUpdatedAt(LocalDateTime.now()); userMapper.insert(user); return user.getId(); } Override public Boolean updateUser(User user) { user.setUpdatedAt(LocalDateTime.now()); return userMapper.updateById(user) 0; } Override public Boolean deleteUser(Long id) { return userMapper.deleteById(id) 0; } Override public ListUser listUsers() { return userMapper.selectList(null); } }注意構(gòu)造器注入的寫(xiě)法。在 Spring 官方文檔里構(gòu)造器注入是推薦的依賴(lài)注入方式它讓依賴(lài)關(guān)系不可變、不容易產(chǎn)生循環(huán)依賴(lài)也方便單元測(cè)試。我早期寫(xiě) Spring 項(xiàng)目時(shí)習(xí)慣用Autowired字段注入直到一次排查空指針問(wèn)題發(fā)現(xiàn)是依賴(lài)沒(méi)有初始化完成從那以后就轉(zhuǎn)向了構(gòu)造器注入。4.4 Controller 層與統(tǒng)一返回結(jié)構(gòu)Controller 層直接暴露 HTTP 接口但我不建議直接把實(shí)體返回給前端更規(guī)范的做法是引入一個(gè)統(tǒng)一返回體。這里用一個(gè)極簡(jiǎn)的RT類(lèi)Data public class RT { private Integer code; private String message; private T data; public static T RT ok(T data) { RT r new R(); r.setCode(200); r.setMessage(success); r.setData(data); return r; } public static T RT error(String message) { RT r new R(); r.setCode(500); r.setMessage(message); return r; } }Controller 如下RestController RequestMapping(/user) RequiredArgsConstructor public class UserController { private final UserService userService; GetMapping(/{id}) public RUser getUserById(PathVariable Long id) { return R.ok(userService.getUserById(id)); } PostMapping public RLong createUser(RequestBody User user) { return R.ok(userService.createUser(user)); } PutMapping public RBoolean updateUser(RequestBody User user) { return R.ok(userService.updateUser(user)); } DeleteMapping(/{id}) public RBoolean deleteUser(PathVariable Long id) { return R.ok(userService.deleteUser(id)); } GetMapping public RListUser listUsers() { return R.ok(userService.listUsers()); } }到這一步user-service已經(jīng)是一個(gè)具備完整 CRUD 能力的 HTTP 服務(wù)了。你可以直接用瀏覽器或者 Postman 訪(fǎng)問(wèn)http://127.0.0.1:8081/user/1測(cè)試一下能返回 JSON 就說(shuō)明業(yè)務(wù)側(cè)已經(jīng)跑通。但這不是微服務(wù)的完整形態(tài)接下來(lái)要做的是把服務(wù)納入網(wǎng)關(guān)并演示服務(wù)間如何調(diào)用。5. 網(wǎng)關(guān)與服務(wù)間調(diào)用請(qǐng)求鏈路的最后一公里5.1 Gateway 的角色定位與配置網(wǎng)關(guān)是微服務(wù)架構(gòu)里所有外部請(qǐng)求的統(tǒng)一入口。你可以把它理解成一個(gè)前臺(tái)收發(fā)室外面的人不知道每個(gè)辦公室服務(wù)具體在哪只要把快遞請(qǐng)求交給收發(fā)室收發(fā)室根據(jù)地址路由規(guī)則分發(fā)給對(duì)應(yīng)的辦公室。創(chuàng)建gateway-service子模塊pom.xml引入dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency配置文件server: port: 8080 spring: application: name: gateway-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 gateway: routes: - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1 logging: level: org.springframework.cloud.gateway: debug這里的路由配置拆開(kāi)看id路由的唯一標(biāo)識(shí)自定義即可。uri: lb://user-servicelb://前綴表示啟用負(fù)載均衡后面跟的是服務(wù)名Gateway 會(huì)從 Nacos 拉取user-service的實(shí)例列表并按負(fù)載均衡策略進(jìn)行分發(fā)。predicates路由斷言Path/api/user/**表示以/api/user/開(kāi)頭的請(qǐng)求都會(huì)命中這條路由。filters: StripPrefix1轉(zhuǎn)發(fā)到下游服務(wù)前去掉路徑中的第一級(jí)前綴。舉個(gè)例子外部請(qǐng)求GET http://127.0.0.1:8080/api/user/1經(jīng)過(guò) Gateway 后StripPrefix1會(huì)去掉api變成/user/1然后轉(zhuǎn)發(fā)到user-service的/user/1接口。這樣前端調(diào)用可以統(tǒng)一帶/api前綴而每個(gè)微服務(wù)內(nèi)部接口不需要關(guān)心外部前綴是什么。5.2 為什么 Gateway 不能和 spring-boot-starter-web 共存這是一個(gè)高頻踩坑點(diǎn)。Gateway 底層基于 Spring WebFlux使用的是 Reactor Netty 響應(yīng)式模型spring-boot-starter-web則是傳統(tǒng)的 Servlet 模型基于 Tomcat。兩者同時(shí)出現(xiàn)在類(lèi)路徑下時(shí)Spring Boot 的自動(dòng)配置會(huì)發(fā)生沖突典型報(bào)錯(cuò)是Spring MVC found on classpath, which is incompatible with Spring Cloud Gateway解決方案只有一個(gè)gateway-service 的 pom.xml 里不要引入spring-boot-starter-web。如果你是從別的項(xiàng)目拷貝 pom 過(guò)來(lái)很容易帶出這個(gè)依賴(lài)啟動(dòng)時(shí)報(bào)錯(cuò)后需要仔細(xì)核對(duì)依賴(lài)樹(shù)mvn dependency:tree -Dincludesorg.springframework.boot:spring-boot-starter-web5.3 用 OpenFeign 實(shí)現(xiàn)服務(wù)間調(diào)用CRUD 場(chǎng)景里網(wǎng)關(guān)把請(qǐng)求路由到user-service就夠了但很多時(shí)候業(yè)務(wù)會(huì)有跨服務(wù)的數(shù)據(jù)需求。比如訂單服務(wù)需要查詢(xún)用戶(hù)信息這就涉及服務(wù)間調(diào)用。OpenFeign 是 Spring Cloud 生態(tài)里最主流的聲明式 HTTP 客戶(hù)端。先在一個(gè)獨(dú)立的模塊或者任意服務(wù)里定義 Feign 接口。這里為了演示我在user-service里加一個(gè)UserClient模擬被網(wǎng)關(guān)服務(wù)調(diào)用FeignClient(name user-service, path /user) public interface UserClient { GetMapping(/{id}) RUser getById(PathVariable(id) Long id); }FeignClient注解里的name是目標(biāo)服務(wù)在注冊(cè)中心的服務(wù)名path是公共路徑前綴。方法定義和 Spring MVC Controller 的映射寫(xiě)法一致OpenFeign 會(huì)在運(yùn)行時(shí)動(dòng)態(tài)生成實(shí)現(xiàn)類(lèi)發(fā) HTTP 請(qǐng)求到目標(biāo)服務(wù)的對(duì)應(yīng)接口。調(diào)用方啟動(dòng)類(lèi)加上EnableFeignClientsEnableFeignClients SpringBootApplication public class SomeServiceApplication { public static void main(String[] args) { SpringApplication.run(SomeServiceApplication.class, args); } }然后就可以像注入普通 Service 一樣使用UserClientService public class OrderService { private final UserClient userClient; public User getUserInfo(Long userId) { return userClient.getById(userId); } }這里 OpenFeign 會(huì)配合負(fù)載均衡組件以服務(wù)名user-service從注冊(cè)中心拿到真實(shí)地址然后完成調(diào)用。整個(gè)過(guò)程對(duì)業(yè)務(wù)代碼完全透明你不需要關(guān)心目標(biāo)服務(wù)的 IP 和端口。5.4 負(fù)載均衡策略的小知識(shí)在 Spring Cloud 2021.x 里原來(lái)的 Ribbon 客戶(hù)端已經(jīng)被 Spring Cloud LoadBalancer 取代。默認(rèn)的負(fù)載均衡策略是輪詢(xún)Round Robin如果你需要改成隨機(jī)策略可以通過(guò)配置實(shí)現(xiàn)。不過(guò)在剛開(kāi)始整合階段輪詢(xún)夠用了先跑通鏈路再說(shuō)不要過(guò)早優(yōu)化策略。6. 本地完整啟動(dòng)驗(yàn)證與高頻踩坑記錄6.1 啟動(dòng)順序很重要我把啟動(dòng)流程固定下來(lái)按這個(gè)順序操作可以最大程度減少排查成本啟動(dòng) MySQL確認(rèn)crud_demo庫(kù)和user表存在。啟動(dòng) Nacos Server瀏覽器訪(fǎng)問(wèn)控制臺(tái)確認(rèn)可用。啟動(dòng)user-service確認(rèn) Nacos 服務(wù)列表中出現(xiàn)該服務(wù)。啟動(dòng)gateway-service同樣確認(rèn)注冊(cè)成功。通過(guò)網(wǎng)關(guān)發(fā)起請(qǐng)求驗(yàn)證完整鏈路。驗(yàn)證請(qǐng)求建議用這幾個(gè)# 新增用戶(hù)注意走網(wǎng)關(guān)端口 8080 curl -X POST http://127.0.0.1:8080/api/user \ -H Content-Type: application/json \ -d {username: test_user, email: testexample.com, phone: 13800000000} # 查詢(xún)用戶(hù) curl http://127.0.0.1:8080/api/user/1 # 查詢(xún)所有用戶(hù) curl http://127.0.0.1:8080/api/user # 更新用戶(hù) curl -X PUT http://127.0.0.1:8080/api/user \ -H Content-Type: application/json \ -d {id: 1, username: updated_user, email: updatedexample.com} # 刪除用戶(hù) curl -X DELETE http://127.0.0.1:8080/api/user/1如果刪掉了用戶(hù)記得再插一條數(shù)據(jù)做后續(xù)測(cè)試或者把刪除請(qǐng)求放到最后執(zhí)行。6.2 我實(shí)際遇到過(guò)的幾個(gè)問(wèn)題問(wèn)題一Nacos 注冊(cè)成功但 Gateway 轉(zhuǎn)發(fā)報(bào) 503這個(gè)問(wèn)題的典型場(chǎng)景是user-service在 Nacos 里顯示健康但通過(guò)網(wǎng)關(guān)訪(fǎng)問(wèn)時(shí)返回 503 Service Unavailable。排查步驟我也是踩了幾次坑才總結(jié)出來(lái)的先直接訪(fǎng)問(wèn)http://127.0.0.1:8081/user/1確認(rèn)服務(wù)本身健康。再檢查 Gateway 的配置重點(diǎn)看uri是不是lb://user-service拼寫(xiě)是否正確。lb://不能少少了下游地址無(wú)法解析。看 Gateway 日志如果出現(xiàn)Unable to load instance之類(lèi)的關(guān)鍵字多半是 Nacos 上服務(wù)的實(shí)例狀態(tài)異?？赡苁亲?cè)了多個(gè)環(huán)境比如 dev 和 test 用了同一個(gè) Nacos可以通過(guò)namespace隔離。問(wèn)題二MyBatis-Plus 的 LocalDateTime 反序列化報(bào)錯(cuò)前端傳 JSON 給后端后端返回 JSON 給前端LocalDateTime 字段會(huì)面臨序列化格式問(wèn)題。如果不做配置返回的可能是數(shù)組形式的[2025, 3, 15, 10, 30, 0]前端解析會(huì)很痛苦。我在user-service里加了統(tǒng)一的 Jackson 配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8注意這個(gè)配置對(duì)LocalDateTime類(lèi)型的字段不一定生效因?yàn)?LocalDateTime 默認(rèn)是由 JSR310 模塊序列化的。為了穩(wěn)妥我在字段上添加了注解JsonFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime createdAt;問(wèn)題三啟動(dòng)時(shí)端口被占本地調(diào)試多個(gè)微服務(wù)時(shí)端口沖突是?？汀inux/macOS 用lsof -i :8081查看占用端口的進(jìn)程Windows 用netstat -ano | findstr 8081。也可以直接把微服務(wù)的端口號(hào)都改成隨機(jī)端口server: port: 0但這樣服務(wù)名就成了唯一標(biāo)識(shí)如果你后面調(diào)試時(shí)要通過(guò)固定端口訪(fǎng)問(wèn)反而更麻煩。本地學(xué)習(xí)階段還是建議固定端口。問(wèn)題四OpenFeign 調(diào)用時(shí)復(fù)雜對(duì)象參數(shù)丟失這是我曾經(jīng)疏忽的地方Feign 接口方法里如果有多個(gè)參數(shù)必須用PathVariable或者RequestParam顯式標(biāo)注參數(shù)名。如果漏了注解編譯時(shí)參數(shù)名會(huì)被擦除導(dǎo)致請(qǐng)求發(fā)送出去后目標(biāo)服務(wù)收到null。構(gòu)建時(shí)可以用-parameters參數(shù)保留元數(shù)據(jù)但最穩(wěn)妥的做法還是每個(gè)參數(shù)都加上對(duì)應(yīng)注解。6.3 這篇整合對(duì)后續(xù)系列的意義到這里一個(gè)帶注冊(cè)發(fā)現(xiàn)、網(wǎng)關(guān)路由、服務(wù)間調(diào)用、全鏈路 CRUD 的微服務(wù)骨架已經(jīng)完成。你擁有了一個(gè)隨時(shí)可以擴(kuò)展的基礎(chǔ)設(shè)施再加業(yè)務(wù)模塊時(shí)只需要新建一個(gè)子模塊寫(xiě)上業(yè)務(wù)代碼注冊(cè)到 Nacos然后在網(wǎng)關(guān)里加一條路由即可。實(shí)際上這也是我寫(xiě)這一篇整合的初衷。很多人覺(jué)得微服務(wù)難不是難在概念而是難在第一次把整套東西串起來(lái)。一旦串起來(lái)之后就會(huì)發(fā)現(xiàn)后端的治理組件配置中心、熔斷、鏈路追蹤都是在這個(gè)骨架上不斷做加法。下一篇整合我打算寫(xiě)配置中心的接入也就是把user-service里的數(shù)據(jù)源配置挪到 Nacos 配置中心做到配置動(dòng)態(tài)刷新。那件事做完之后你會(huì)對(duì)配置和代碼分離有更直觀的感受。7. 一組可以直接抄作業(yè)的工程配置清單為了照顧不同閱讀習(xí)慣的同學(xué)我把整個(gè)工程的關(guān)鍵配置以清單形式再匯總一遍。按照下面的清單核對(duì)基本可以避免遺漏。模塊配置文件關(guān)鍵配置項(xiàng)父工程 pom.xmlspring-cloud-dependencies2021.0.8統(tǒng)一管理 Spring Cloud 組件版本父工程 pom.xmlspring-cloud-alibaba-dependencies2021.0.5.0統(tǒng)一管理 Nacos 等 Alibaba 組件版本user-serviceapplication.ymlnacos discovery、datasource、mybatis-plus 配置user-servicepom.xmlstarter-web、nacos-discovery、mybatis-plus、openfeign、mysqlgateway-serviceapplication.ymlnacos discovery、gateway routes含 StripPrefix1gateway-servicepom.xmlstarter-gateway、nacos-discovery不引入 starter-web依賴(lài)與注解方面的核對(duì)點(diǎn)如下啟動(dòng)類(lèi)上要有SpringBootApplication需要注冊(cè)發(fā)現(xiàn)就加EnableDiscoveryClient需要 Feign 就加EnableFeignClients。Mapper注解讓 MyBatis 掃描到 Mapper 接口或者在啟動(dòng)類(lèi)上使用MapperScan(com.example.mapper)批量掃描。Controller 層統(tǒng)一返回RT后續(xù)加全局異常處理器時(shí)才能保證異常和正常返回的結(jié)構(gòu)一致。Gateway 路由配置中l(wèi)b://前綴表示負(fù)載均衡服務(wù)名要和 Nacos 上注冊(cè)的一致。8. 關(guān)于這個(gè)骨架我還想強(qiáng)調(diào)的幾件事第一微服務(wù)整合不是越復(fù)雜越好?，F(xiàn)在 Spring Cloud 生態(tài)里的組件非常多熔斷、限流、鏈路跟蹤、分布式事務(wù)各有各的場(chǎng)景。但如果你剛起步就把這些全部引入任何一個(gè)環(huán)節(jié)出問(wèn)題排查起來(lái)都會(huì)非常痛苦。先維護(hù)一個(gè)最小可用的鏈路是我驗(yàn)證過(guò)最穩(wěn)妥的推進(jìn)方式。第二本地調(diào)試時(shí)日志就是最好的老師。我在本地調(diào)試時(shí)會(huì)把 MyBatis-Plus 的 SQL 日志打開(kāi)3.3 配置里的log-impl也把 Gateway 的日志級(jí)別調(diào)成 debug。這樣做的好處是請(qǐng)求到達(dá)哪個(gè)環(huán)節(jié)、SQL 執(zhí)行了什么、路由轉(zhuǎn)發(fā)到了哪里全部一目了然。很多同學(xué)遇到 500 錯(cuò)誤就發(fā)懵其實(shí)把日志翻一翻很多問(wèn)題都能找到答案。第三關(guān)于 OpenFeign 和 Gateway 的整合順序我見(jiàn)過(guò)有些人先做網(wǎng)關(guān)后做 Feign導(dǎo)致調(diào)試時(shí)鏈路太多分不清問(wèn)題在哪。我建議的順序是先直連確認(rèn)服務(wù)本身沒(méi)問(wèn)題再通過(guò) Feign 做服務(wù)間調(diào)用最后接入網(wǎng)關(guān)統(tǒng)一入口。一步一步驗(yàn)證每一步的結(jié)論都是確定的這樣最終鏈路出問(wèn)題時(shí)可以迅速定位是哪個(gè)環(huán)節(jié)引入的。這篇文章到這里Spring Cloud 整合 CRUD 就已經(jīng)全部跑通了。整個(gè)過(guò)程中我刻意避開(kāi)了那些炫技式的高級(jí)配置只保留必需的部分。理由很簡(jiǎn)單你先把這條最基礎(chǔ)的鏈路走通下一篇文章在配置中心里改數(shù)據(jù)源配置時(shí)才能意識(shí)到什么叫改動(dòng)一處服務(wù)不重啟。那才是微服務(wù)治理真正有意思的開(kāi)始。 Spring Cloud微服務(wù)整合CRUD：從Nacos注冊(cè)到OpenFeign調(diào)用的完整實(shí)踐
1. 為什么這個(gè)系列的第一篇要寫(xiě)CRUD微服務(wù)落地的第一塊敲門(mén)磚先說(shuō)一個(gè)很多人容易誤解的點(diǎn)Spring Cloud 是個(gè)宏觀的微服務(wù)治理方案名字里帶個(gè)云字但實(shí)際上它解決的不是業(yè)務(wù)代碼怎么寫(xiě)而是多個(gè)服務(wù)進(jìn)程之間怎么組織、怎么發(fā)現(xiàn)、怎么通信、怎么容錯(cuò)。CRUD 則是任何業(yè)務(wù)系統(tǒng)里最基礎(chǔ)、也最繞不開(kāi)的數(shù)據(jù)操作能力。把 Spring Cloud 和 CRUD 放到一起整合本質(zhì)上是做這樣一件事讓一個(gè)業(yè)務(wù)模塊以微服務(wù)的方式跑起來(lái)并且通過(guò)注冊(cè)中心、網(wǎng)關(guān)、服務(wù)調(diào)用這些 Spring Cloud 核心組件完成完整的請(qǐng)求鏈路。我自己的體會(huì)是網(wǎng)上一搜 Spring Cloud鋪天蓋地都是注冊(cè)中心原理網(wǎng)關(guān)過(guò)濾器分布式事務(wù)這些偏治理側(cè)的內(nèi)容反而很少有人把一個(gè)最簡(jiǎn)單的用戶(hù)模塊從數(shù)據(jù)庫(kù)到前端接口完整走通微服務(wù)調(diào)用鏈這件事講清楚。但實(shí)際項(xiàng)目落地的時(shí)候你第一步需要的就是一個(gè)能跑通的 CRUD 服務(wù)因?yàn)樗逆溌纷疃?、?wèn)題最直觀、也最適合用來(lái)驗(yàn)證整套基礎(chǔ)設(shè)施是否正常。這篇文章定位為Spring Cloud 整合一適合兩類(lèi)人一類(lèi)是剛接觸微服務(wù)、想搭一套本地可運(yùn)行 Demo 的開(kāi)發(fā)者另一類(lèi)是已經(jīng)用單體寫(xiě)過(guò)很多 CRUD、想看看同一套業(yè)務(wù)代碼放到微服務(wù)架構(gòu)里會(huì)發(fā)生什么變化的同學(xué)。文章里我會(huì)把選型理由、配置細(xì)節(jié)、啟動(dòng)順序、踩坑記錄一次講透保證你照著做能跑起來(lái)而不是看了一堆抽象概念。整體架構(gòu)我會(huì)控制在三個(gè)服務(wù)內(nèi)一個(gè)用于演示 CRUD 的user-service一個(gè)負(fù)責(zé)轉(zhuǎn)發(fā)請(qǐng)求的網(wǎng)關(guān)服務(wù)gateway-service再加上注冊(cè)中心 Nacos。后文還會(huì)引入 OpenFeign 演示服務(wù)間調(diào)用這也是微服務(wù)場(chǎng)景下最典型的用法。2. 版本選型與父工程搭建這一步?jīng)Q定后面三個(gè)月是否順利2.1 Spring Cloud 與 Spring Boot 的版本對(duì)應(yīng)關(guān)系Spring Cloud 的版本號(hào)經(jīng)歷了一次重要變化。早期用Dalston、Edgware、Hoxton這類(lèi)倫敦地鐵站名來(lái)命名從2020.0開(kāi)始改成了年份命名方式。很多新手在這里第一個(gè)坑就是Spring Cloud 和 Spring Boot 必須嚴(yán)格匹配否則啟動(dòng)時(shí)會(huì)報(bào)各種莫名其妙的 NoClassDefFoundError 或者 Bean 創(chuàng)建異常。我這里直接給出兩套經(jīng)過(guò)驗(yàn)證的穩(wěn)定組合你可以按自己的 JDK 情況選組合JDKSpring BootSpring CloudSpring Cloud Alibaba傳統(tǒng)穩(wěn)定組合8/112.7.182021.0.82021.0.5.0新版組合173.2.x2023.0.x2023.0.1.0我個(gè)人建議如果是為了學(xué)習(xí)和本地驗(yàn)證優(yōu)先選第一套JDK 8 Spring Boot 2.7.18 Spring Cloud 2021.0.8。原因很現(xiàn)實(shí)這套組合的網(wǎng)上資料最多遇到問(wèn)題一搜就有答案而且 Nacos、Gateway、OpenFeign 這些組件的兼容性都已經(jīng)被大量生產(chǎn)項(xiàng)目驗(yàn)證過(guò)了。Spring Boot 3.x 雖然新但 Jakarta EE 的包名遷移、Spring Security 6 的配置變化對(duì)初學(xué)者來(lái)說(shuō)排查成本偏高。2.2 父 POM 的依賴(lài)管理我會(huì)創(chuàng)建一個(gè) Maven 父工程只放依賴(lài)管理和公共屬性不寫(xiě)業(yè)務(wù)代碼。這樣做的好處是子模塊之間版本統(tǒng)一后續(xù)引入新的微服務(wù)模塊時(shí)不需要再重復(fù)指定版本號(hào)。父 POM 的核心內(nèi)容如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent properties spring-cloud.version2021.0.8/spring-cloud.version spring-cloud-alibaba.version2021.0.5.0/spring-cloud-alibaba.version mybatis-plus.version3.5.3.2/mybatis-plus.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version${spring-cloud-alibaba.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意dependencyManagement里的import方式。它不像普通依賴(lài)那樣把 jar 直接引入而是把對(duì)應(yīng) BOM 里的版本管理信息導(dǎo)入當(dāng)前 POM。這樣你在子模塊里寫(xiě)依賴(lài)的時(shí)候可以不加versionMaven 會(huì)自動(dòng)找父工程里鎖定的版本。2.3 子模塊的拆分方式父工程下我會(huì)建兩個(gè)子模塊分別對(duì)應(yīng)兩個(gè)可啟動(dòng)的服務(wù)spring-cloud-crud-demo ├── pom.xml # 父工程 ├── gateway-service/ # 網(wǎng)關(guān)服務(wù) └── user-service/ # 用戶(hù)服務(wù)承載 CRUD 業(yè)務(wù)嚴(yán)格來(lái)說(shuō)網(wǎng)關(guān)也是微服務(wù)的一個(gè)成員所以它也要注冊(cè)到 Nacos只是它的職責(zé)不是處理業(yè)務(wù)而是做路由轉(zhuǎn)發(fā)。兩個(gè)子模塊的pom.xml里只需聲明自身需要的依賴(lài)即可。user-service的依賴(lài)如下dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version${mybatis-plus.version}/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency /dependenciesgateway-service的依賴(lài)則要注意不要加spring-boot-starter-web。這一點(diǎn)我在后面會(huì)專(zhuān)門(mén)講Gateway 基于 WebFlux 響應(yīng)式模型和傳統(tǒng)的 Servlet Web 容器沖突加了就啟動(dòng)報(bào)錯(cuò)。3. 注冊(cè)中心接入用 Nacos 讓服務(wù)先彼此看見(jiàn)3.1 為什么選擇 Nacos 而不是 EurekaEureka 2.x 已經(jīng)停止維護(hù)這已經(jīng)是共識(shí)。Nacos 是阿里巴巴開(kāi)源的服務(wù)發(fā)現(xiàn)與配置管理組件目前在國(guó)內(nèi)微服務(wù)項(xiàng)目中占絕對(duì)主流。選它的理由很簡(jiǎn)單既能做服務(wù)注冊(cè)發(fā)現(xiàn)又能做配置中心一套組件解決兩個(gè)問(wèn)題而且和 Spring Cloud Alibaba 生態(tài)結(jié)合得非常順滑。后文如果繼續(xù)寫(xiě)這個(gè)系列配置中心的整合就會(huì)直接基于 Nacos不需要額外引入新組件。3.2 本地啟動(dòng) Nacos ServerNacos Server 的啟動(dòng)方式有源碼編譯、Docker、下載發(fā)行包三種。對(duì)于本地驗(yàn)證我推薦直接下載最新穩(wěn)定版發(fā)行包# 解壓后進(jìn)入 bin 目錄Linux/macOS 執(zhí)行 sh startup.sh -m standalone # Windows 執(zhí)行 startup.cmd -m standalonestandalone參數(shù)表示單機(jī)模式Nacos 默認(rèn)使用內(nèi)置的 Derby 數(shù)據(jù)庫(kù)存儲(chǔ)服務(wù)實(shí)例信息不需要額外安裝數(shù)據(jù)庫(kù)。啟動(dòng)成功后訪(fǎng)問(wèn)http://127.0.0.1:8848/nacos默認(rèn)用戶(hù)名密碼都是nacos能看到控制臺(tái)界面就說(shuō)明注冊(cè)中心已經(jīng)就緒。3.3 user-service 接入 Nacosuser-service的application.yml中配置如下server: port: 8081 spring: application: name: user-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: public group: DEFAULT_GROUP datasource: url: jdbc:mysql://127.0.0.1:3306/crud_demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto幾個(gè)關(guān)鍵點(diǎn)解釋一下spring.application.name是服務(wù)在注冊(cè)中心里的唯一標(biāo)識(shí)也是后面服務(wù)間調(diào)用和網(wǎng)關(guān)路由的關(guān)鍵依據(jù)。名字別亂起建議用中劃線(xiàn)分隔比如user-service而不是userService。namespace和group可以在沒(méi)有顯式配置時(shí)省略默認(rèn)就是public和DEFAULT_GROUP。但我在實(shí)際項(xiàng)目里建議一開(kāi)始就顯式寫(xiě)出來(lái)因?yàn)楹罄m(xù)做環(huán)境隔離dev/test/prod 各占一個(gè) namespace時(shí)你會(huì)理解這兩個(gè)參數(shù)的意義。3.4 啟動(dòng)類(lèi)上加注解在UserServiceApplication上加上EnableDiscoveryClientSpringBootApplication EnableDiscoveryClient public class UserServiceApplication { public static void main(String[] args) { SpringApplication.run(UserServiceApplication.class, args); } }在 Spring Cloud 2021.x 版本里注冊(cè)發(fā)現(xiàn)能力已經(jīng)默認(rèn)開(kāi)啟不加這個(gè)注解也能注冊(cè)但我建議保留。原因有兩個(gè)一是顯式表明這個(gè)服務(wù)要參與服務(wù)發(fā)現(xiàn)二是如果你做一些自定義的注冊(cè)邏輯或者需要注入 DiscoveryClient 對(duì)象時(shí)這個(gè)注解會(huì)讓代碼意圖更清晰。啟動(dòng)user-service后回到 Nacos 控制臺(tái)服務(wù)列表里應(yīng)該能看到user-service已經(jīng)注冊(cè)上來(lái)狀態(tài)為健康。4. CRUD 三件套的實(shí)現(xiàn)實(shí)體、持久層、接口層微服務(wù)架構(gòu)下的業(yè)務(wù)代碼寫(xiě)法其實(shí)和單體項(xiàng)目沒(méi)有本質(zhì)區(qū)別。這也是我特別想強(qiáng)調(diào)的一點(diǎn)Spring Cloud 的整合重點(diǎn)在基礎(chǔ)設(shè)施和通信鏈路而不是讓你把熟悉的 CRUD 寫(xiě)法推翻重來(lái)。4.1 數(shù)據(jù)庫(kù)準(zhǔn)備先準(zhǔn)備一張簡(jiǎn)單的用戶(hù)表CREATE DATABASE IF NOT EXISTS crud_demo DEFAULT CHARACTER SET utf8mb4; USE crud_demo; CREATE TABLE user ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT 主鍵ID, username VARCHAR(64) NOT NULL COMMENT 用戶(hù)名, email VARCHAR(128) DEFAULT NULL COMMENT 郵箱, phone VARCHAR(20) DEFAULT NULL COMMENT 手機(jī)號(hào), created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新時(shí)間, PRIMARY KEY (id) ) ENGINE InnoDB DEFAULT CHARSET utf8mb4 COMMENT 用戶(hù)表;這里有個(gè)字段命名的小細(xì)節(jié)數(shù)據(jù)庫(kù)字段用下劃線(xiàn)風(fēng)格created_atJava 實(shí)體用駝峰風(fēng)格createdAt。MyBatis-Plus 的map-underscore-to-camel-case配置會(huì)自動(dòng)做映射省去大量手寫(xiě) ResultMap 的工作。我在 3.3 里的配置已經(jīng)打開(kāi)了這個(gè)開(kāi)關(guān)。4.2 實(shí)體類(lèi)與 Mapper實(shí)體類(lèi)對(duì)應(yīng)表結(jié)構(gòu)Data TableName(user) public class User { TableId(type IdType.AUTO) private Long id; private String username; private String email; private String phone; private LocalDateTime createdAt; private LocalDateTime updatedAt; }TableName(user)注解是因?yàn)閡ser這個(gè)表名不是 Java 命名規(guī)范的駝峰形式如果不注解MyBatis-Plus 會(huì)默認(rèn)映射到user實(shí)體類(lèi)名正好也能對(duì)上但為了保險(xiǎn)起見(jiàn)還是顯式標(biāo)注。Mapper 接口更簡(jiǎn)單Mapper public interface UserMapper extends BaseMapperUser { }BaseMapperT是 MyBatis-Plus 提供的通用 CRUD Mapper內(nèi)置了selectById、insert、updateById、deleteById、selectList等方法。正常情況下你不需要寫(xiě)任何 XML 映射文件也不需要寫(xiě) SQL 語(yǔ)句。這套寫(xiě)法的好處是一個(gè)實(shí)體對(duì)應(yīng)一個(gè) MapperCRUD 的基礎(chǔ)方法全部開(kāi)箱即用。4.3 Service 層的接口與實(shí)現(xiàn)Service 層建議按接口 實(shí)現(xiàn)類(lèi)的模式拆開(kāi)雖然代碼量多一些但在業(yè)務(wù)復(fù)雜后你會(huì)受益于這種隔離public interface UserService { User getUserById(Long id); Long createUser(User user); Boolean updateUser(User user); Boolean deleteUser(Long id); ListUser listUsers(); } Service RequiredArgsConstructor public class UserServiceImpl implements UserService { private final UserMapper userMapper; Override public User getUserById(Long id) { return userMapper.selectById(id); } Override public Long createUser(User user) { user.setCreatedAt(LocalDateTime.now()); user.setUpdatedAt(LocalDateTime.now()); userMapper.insert(user); return user.getId(); } Override public Boolean updateUser(User user) { user.setUpdatedAt(LocalDateTime.now()); return userMapper.updateById(user) 0; } Override public Boolean deleteUser(Long id) { return userMapper.deleteById(id) 0; } Override public ListUser listUsers() { return userMapper.selectList(null); } }注意構(gòu)造器注入的寫(xiě)法。在 Spring 官方文檔里構(gòu)造器注入是推薦的依賴(lài)注入方式它讓依賴(lài)關(guān)系不可變、不容易產(chǎn)生循環(huán)依賴(lài)也方便單元測(cè)試。我早期寫(xiě) Spring 項(xiàng)目時(shí)習(xí)慣用Autowired字段注入直到一次排查空指針問(wèn)題發(fā)現(xiàn)是依賴(lài)沒(méi)有初始化完成從那以后就轉(zhuǎn)向了構(gòu)造器注入。4.4 Controller 層與統(tǒng)一返回結(jié)構(gòu)Controller 層直接暴露 HTTP 接口但我不建議直接把實(shí)體返回給前端更規(guī)范的做法是引入一個(gè)統(tǒng)一返回體。這里用一個(gè)極簡(jiǎn)的RT類(lèi)Data public class RT { private Integer code; private String message; private T data; public static T RT ok(T data) { RT r new R(); r.setCode(200); r.setMessage(success); r.setData(data); return r; } public static T RT error(String message) { RT r new R(); r.setCode(500); r.setMessage(message); return r; } }Controller 如下RestController RequestMapping(/user) RequiredArgsConstructor public class UserController { private final UserService userService; GetMapping(/{id}) public RUser getUserById(PathVariable Long id) { return R.ok(userService.getUserById(id)); } PostMapping public RLong createUser(RequestBody User user) { return R.ok(userService.createUser(user)); } PutMapping public RBoolean updateUser(RequestBody User user) { return R.ok(userService.updateUser(user)); } DeleteMapping(/{id}) public RBoolean deleteUser(PathVariable Long id) { return R.ok(userService.deleteUser(id)); } GetMapping public RListUser listUsers() { return R.ok(userService.listUsers()); } }到這一步user-service已經(jīng)是一個(gè)具備完整 CRUD 能力的 HTTP 服務(wù)了。你可以直接用瀏覽器或者 Postman 訪(fǎng)問(wèn)http://127.0.0.1:8081/user/1測(cè)試一下能返回 JSON 就說(shuō)明業(yè)務(wù)側(cè)已經(jīng)跑通。但這不是微服務(wù)的完整形態(tài)接下來(lái)要做的是把服務(wù)納入網(wǎng)關(guān)并演示服務(wù)間如何調(diào)用。5. 網(wǎng)關(guān)與服務(wù)間調(diào)用請(qǐng)求鏈路的最后一公里5.1 Gateway 的角色定位與配置網(wǎng)關(guān)是微服務(wù)架構(gòu)里所有外部請(qǐng)求的統(tǒng)一入口。你可以把它理解成一個(gè)前臺(tái)收發(fā)室外面的人不知道每個(gè)辦公室服務(wù)具體在哪只要把快遞請(qǐng)求交給收發(fā)室收發(fā)室根據(jù)地址路由規(guī)則分發(fā)給對(duì)應(yīng)的辦公室。創(chuàng)建gateway-service子模塊pom.xml引入dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency配置文件server: port: 8080 spring: application: name: gateway-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 gateway: routes: - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1 logging: level: org.springframework.cloud.gateway: debug這里的路由配置拆開(kāi)看id路由的唯一標(biāo)識(shí)自定義即可。uri: lb://user-servicelb://前綴表示啟用負(fù)載均衡后面跟的是服務(wù)名Gateway 會(huì)從 Nacos 拉取user-service的實(shí)例列表并按負(fù)載均衡策略進(jìn)行分發(fā)。predicates路由斷言Path/api/user/**表示以/api/user/開(kāi)頭的請(qǐng)求都會(huì)命中這條路由。filters: StripPrefix1轉(zhuǎn)發(fā)到下游服務(wù)前去掉路徑中的第一級(jí)前綴。舉個(gè)例子外部請(qǐng)求GET http://127.0.0.1:8080/api/user/1經(jīng)過(guò) Gateway 后StripPrefix1會(huì)去掉api變成/user/1然后轉(zhuǎn)發(fā)到user-service的/user/1接口。這樣前端調(diào)用可以統(tǒng)一帶/api前綴而每個(gè)微服務(wù)內(nèi)部接口不需要關(guān)心外部前綴是什么。5.2 為什么 Gateway 不能和 spring-boot-starter-web 共存這是一個(gè)高頻踩坑點(diǎn)。Gateway 底層基于 Spring WebFlux使用的是 Reactor Netty 響應(yīng)式模型spring-boot-starter-web則是傳統(tǒng)的 Servlet 模型基于 Tomcat。兩者同時(shí)出現(xiàn)在類(lèi)路徑下時(shí)Spring Boot 的自動(dòng)配置會(huì)發(fā)生沖突典型報(bào)錯(cuò)是Spring MVC found on classpath, which is incompatible with Spring Cloud Gateway解決方案只有一個(gè)gateway-service 的 pom.xml 里不要引入spring-boot-starter-web。如果你是從別的項(xiàng)目拷貝 pom 過(guò)來(lái)很容易帶出這個(gè)依賴(lài)啟動(dòng)時(shí)報(bào)錯(cuò)后需要仔細(xì)核對(duì)依賴(lài)樹(shù)mvn dependency:tree -Dincludesorg.springframework.boot:spring-boot-starter-web5.3 用 OpenFeign 實(shí)現(xiàn)服務(wù)間調(diào)用CRUD 場(chǎng)景里網(wǎng)關(guān)把請(qǐng)求路由到user-service就夠了但很多時(shí)候業(yè)務(wù)會(huì)有跨服務(wù)的數(shù)據(jù)需求。比如訂單服務(wù)需要查詢(xún)用戶(hù)信息這就涉及服務(wù)間調(diào)用。OpenFeign 是 Spring Cloud 生態(tài)里最主流的聲明式 HTTP 客戶(hù)端。先在一個(gè)獨(dú)立的模塊或者任意服務(wù)里定義 Feign 接口。這里為了演示我在user-service里加一個(gè)UserClient模擬被網(wǎng)關(guān)服務(wù)調(diào)用FeignClient(name user-service, path /user) public interface UserClient { GetMapping(/{id}) RUser getById(PathVariable(id) Long id); }FeignClient注解里的name是目標(biāo)服務(wù)在注冊(cè)中心的服務(wù)名path是公共路徑前綴。方法定義和 Spring MVC Controller 的映射寫(xiě)法一致OpenFeign 會(huì)在運(yùn)行時(shí)動(dòng)態(tài)生成實(shí)現(xiàn)類(lèi)發(fā) HTTP 請(qǐng)求到目標(biāo)服務(wù)的對(duì)應(yīng)接口。調(diào)用方啟動(dòng)類(lèi)加上EnableFeignClientsEnableFeignClients SpringBootApplication public class SomeServiceApplication { public static void main(String[] args) { SpringApplication.run(SomeServiceApplication.class, args); } }然后就可以像注入普通 Service 一樣使用UserClientService public class OrderService { private final UserClient userClient; public User getUserInfo(Long userId) { return userClient.getById(userId); } }這里 OpenFeign 會(huì)配合負(fù)載均衡組件以服務(wù)名user-service從注冊(cè)中心拿到真實(shí)地址然后完成調(diào)用。整個(gè)過(guò)程對(duì)業(yè)務(wù)代碼完全透明你不需要關(guān)心目標(biāo)服務(wù)的 IP 和端口。5.4 負(fù)載均衡策略的小知識(shí)在 Spring Cloud 2021.x 里原來(lái)的 Ribbon 客戶(hù)端已經(jīng)被 Spring Cloud LoadBalancer 取代。默認(rèn)的負(fù)載均衡策略是輪詢(xún)Round Robin如果你需要改成隨機(jī)策略可以通過(guò)配置實(shí)現(xiàn)。不過(guò)在剛開(kāi)始整合階段輪詢(xún)夠用了先跑通鏈路再說(shuō)不要過(guò)早優(yōu)化策略。6. 本地完整啟動(dòng)驗(yàn)證與高頻踩坑記錄6.1 啟動(dòng)順序很重要我把啟動(dòng)流程固定下來(lái)按這個(gè)順序操作可以最大程度減少排查成本啟動(dòng) MySQL確認(rèn)crud_demo庫(kù)和user表存在。啟動(dòng) Nacos Server瀏覽器訪(fǎng)問(wèn)控制臺(tái)確認(rèn)可用。啟動(dòng)user-service確認(rèn) Nacos 服務(wù)列表中出現(xiàn)該服務(wù)。啟動(dòng)gateway-service同樣確認(rèn)注冊(cè)成功。通過(guò)網(wǎng)關(guān)發(fā)起請(qǐng)求驗(yàn)證完整鏈路。驗(yàn)證請(qǐng)求建議用這幾個(gè)# 新增用戶(hù)注意走網(wǎng)關(guān)端口 8080 curl -X POST http://127.0.0.1:8080/api/user \ -H Content-Type: application/json \ -d {username: test_user, email: testexample.com, phone: 13800000000} # 查詢(xún)用戶(hù) curl http://127.0.0.1:8080/api/user/1 # 查詢(xún)所有用戶(hù) curl http://127.0.0.1:8080/api/user # 更新用戶(hù) curl -X PUT http://127.0.0.1:8080/api/user \ -H Content-Type: application/json \ -d {id: 1, username: updated_user, email: updatedexample.com} # 刪除用戶(hù) curl -X DELETE http://127.0.0.1:8080/api/user/1如果刪掉了用戶(hù)記得再插一條數(shù)據(jù)做后續(xù)測(cè)試或者把刪除請(qǐng)求放到最后執(zhí)行。6.2 我實(shí)際遇到過(guò)的幾個(gè)問(wèn)題問(wèn)題一Nacos 注冊(cè)成功但 Gateway 轉(zhuǎn)發(fā)報(bào) 503這個(gè)問(wèn)題的典型場(chǎng)景是user-service在 Nacos 里顯示健康但通過(guò)網(wǎng)關(guān)訪(fǎng)問(wèn)時(shí)返回 503 Service Unavailable。排查步驟我也是踩了幾次坑才總結(jié)出來(lái)的先直接訪(fǎng)問(wèn)http://127.0.0.1:8081/user/1確認(rèn)服務(wù)本身健康。再檢查 Gateway 的配置重點(diǎn)看uri是不是lb://user-service拼寫(xiě)是否正確。lb://不能少少了下游地址無(wú)法解析。看 Gateway 日志如果出現(xiàn)Unable to load instance之類(lèi)的關(guān)鍵字多半是 Nacos 上服務(wù)的實(shí)例狀態(tài)異?？赡苁亲?cè)了多個(gè)環(huán)境比如 dev 和 test 用了同一個(gè) Nacos可以通過(guò)namespace隔離。問(wèn)題二MyBatis-Plus 的 LocalDateTime 反序列化報(bào)錯(cuò)前端傳 JSON 給后端后端返回 JSON 給前端LocalDateTime 字段會(huì)面臨序列化格式問(wèn)題。如果不做配置返回的可能是數(shù)組形式的[2025, 3, 15, 10, 30, 0]前端解析會(huì)很痛苦。我在user-service里加了統(tǒng)一的 Jackson 配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8注意這個(gè)配置對(duì)LocalDateTime類(lèi)型的字段不一定生效因?yàn)?LocalDateTime 默認(rèn)是由 JSR310 模塊序列化的。為了穩(wěn)妥我在字段上添加了注解JsonFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime createdAt;問(wèn)題三啟動(dòng)時(shí)端口被占本地調(diào)試多個(gè)微服務(wù)時(shí)端口沖突是?？汀inux/macOS 用lsof -i :8081查看占用端口的進(jìn)程Windows 用netstat -ano | findstr 8081。也可以直接把微服務(wù)的端口號(hào)都改成隨機(jī)端口server: port: 0但這樣服務(wù)名就成了唯一標(biāo)識(shí)如果你后面調(diào)試時(shí)要通過(guò)固定端口訪(fǎng)問(wèn)反而更麻煩。本地學(xué)習(xí)階段還是建議固定端口。問(wèn)題四OpenFeign 調(diào)用時(shí)復(fù)雜對(duì)象參數(shù)丟失這是我曾經(jīng)疏忽的地方Feign 接口方法里如果有多個(gè)參數(shù)必須用PathVariable或者RequestParam顯式標(biāo)注參數(shù)名。如果漏了注解編譯時(shí)參數(shù)名會(huì)被擦除導(dǎo)致請(qǐng)求發(fā)送出去后目標(biāo)服務(wù)收到null。構(gòu)建時(shí)可以用-parameters參數(shù)保留元數(shù)據(jù)但最穩(wěn)妥的做法還是每個(gè)參數(shù)都加上對(duì)應(yīng)注解。6.3 這篇整合對(duì)后續(xù)系列的意義到這里一個(gè)帶注冊(cè)發(fā)現(xiàn)、網(wǎng)關(guān)路由、服務(wù)間調(diào)用、全鏈路 CRUD 的微服務(wù)骨架已經(jīng)完成。你擁有了一個(gè)隨時(shí)可以擴(kuò)展的基礎(chǔ)設(shè)施再加業(yè)務(wù)模塊時(shí)只需要新建一個(gè)子模塊寫(xiě)上業(yè)務(wù)代碼注冊(cè)到 Nacos然后在網(wǎng)關(guān)里加一條路由即可。實(shí)際上這也是我寫(xiě)這一篇整合的初衷。很多人覺(jué)得微服務(wù)難不是難在概念而是難在第一次把整套東西串起來(lái)。一旦串起來(lái)之后就會(huì)發(fā)現(xiàn)后端的治理組件配置中心、熔斷、鏈路追蹤都是在這個(gè)骨架上不斷做加法。下一篇整合我打算寫(xiě)配置中心的接入也就是把user-service里的數(shù)據(jù)源配置挪到 Nacos 配置中心做到配置動(dòng)態(tài)刷新。那件事做完之后你會(huì)對(duì)配置和代碼分離有更直觀的感受。7. 一組可以直接抄作業(yè)的工程配置清單為了照顧不同閱讀習(xí)慣的同學(xué)我把整個(gè)工程的關(guān)鍵配置以清單形式再匯總一遍。按照下面的清單核對(duì)基本可以避免遺漏。模塊配置文件關(guān)鍵配置項(xiàng)父工程 pom.xmlspring-cloud-dependencies2021.0.8統(tǒng)一管理 Spring Cloud 組件版本父工程 pom.xmlspring-cloud-alibaba-dependencies2021.0.5.0統(tǒng)一管理 Nacos 等 Alibaba 組件版本user-serviceapplication.ymlnacos discovery、datasource、mybatis-plus 配置user-servicepom.xmlstarter-web、nacos-discovery、mybatis-plus、openfeign、mysqlgateway-serviceapplication.ymlnacos discovery、gateway routes含 StripPrefix1gateway-servicepom.xmlstarter-gateway、nacos-discovery不引入 starter-web依賴(lài)與注解方面的核對(duì)點(diǎn)如下啟動(dòng)類(lèi)上要有SpringBootApplication需要注冊(cè)發(fā)現(xiàn)就加EnableDiscoveryClient需要 Feign 就加EnableFeignClients。Mapper注解讓 MyBatis 掃描到 Mapper 接口或者在啟動(dòng)類(lèi)上使用MapperScan(com.example.mapper)批量掃描。Controller 層統(tǒng)一返回RT后續(xù)加全局異常處理器時(shí)才能保證異常和正常返回的結(jié)構(gòu)一致。Gateway 路由配置中l(wèi)b://前綴表示負(fù)載均衡服務(wù)名要和 Nacos 上注冊(cè)的一致。8. 關(guān)于這個(gè)骨架我還想強(qiáng)調(diào)的幾件事第一微服務(wù)整合不是越復(fù)雜越好?，F(xiàn)在 Spring Cloud 生態(tài)里的組件非常多熔斷、限流、鏈路跟蹤、分布式事務(wù)各有各的場(chǎng)景。但如果你剛起步就把這些全部引入任何一個(gè)環(huán)節(jié)出問(wèn)題排查起來(lái)都會(huì)非常痛苦。先維護(hù)一個(gè)最小可用的鏈路是我驗(yàn)證過(guò)最穩(wěn)妥的推進(jìn)方式。第二本地調(diào)試時(shí)日志就是最好的老師。我在本地調(diào)試時(shí)會(huì)把 MyBatis-Plus 的 SQL 日志打開(kāi)3.3 配置里的log-impl也把 Gateway 的日志級(jí)別調(diào)成 debug。這樣做的好處是請(qǐng)求到達(dá)哪個(gè)環(huán)節(jié)、SQL 執(zhí)行了什么、路由轉(zhuǎn)發(fā)到了哪里全部一目了然。很多同學(xué)遇到 500 錯(cuò)誤就發(fā)懵其實(shí)把日志翻一翻很多問(wèn)題都能找到答案。第三關(guān)于 OpenFeign 和 Gateway 的整合順序我見(jiàn)過(guò)有些人先做網(wǎng)關(guān)后做 Feign導(dǎo)致調(diào)試時(shí)鏈路太多分不清問(wèn)題在哪。我建議的順序是先直連確認(rèn)服務(wù)本身沒(méi)問(wèn)題再通過(guò) Feign 做服務(wù)間調(diào)用最后接入網(wǎng)關(guān)統(tǒng)一入口。一步一步驗(yàn)證每一步的結(jié)論都是確定的這樣最終鏈路出問(wèn)題時(shí)可以迅速定位是哪個(gè)環(huán)節(jié)引入的。這篇文章到這里Spring Cloud 整合 CRUD 就已經(jīng)全部跑通了。整個(gè)過(guò)程中我刻意避開(kāi)了那些炫技式的高級(jí)配置只保留必需的部分。理由很簡(jiǎn)單你先把這條最基礎(chǔ)的鏈路走通下一篇文章在配置中心里改數(shù)據(jù)源配置時(shí)才能意識(shí)到什么叫改動(dòng)一處服務(wù)不重啟。那才是微服務(wù)治理真正有意思的開(kāi)始。