文章列表

Spring Web 異步 Api

科技新知
MacauYeah・2025-10-18

在設計網頁應用時，總會有某些功能，是特別消耗時間的，例如我們的應用要提供報表，或長時間搜索。如果，我們的 Web Api 的連結，要強制客戶端等待結果，那麼中途斷線需要重做的機會就變得很高，客戶端的體驗一定不太好。 面對這些情況，我們最好就把原本一個 API 功能分為三個 API 去做。 工作生成 API 查詢狀態 API 查詢結果 API 如果大家有信心，可以把2和3混合在一起，對於客戶端，也是一件好事。不過，2,3 因為回傳的結構可能不一樣，分開處理，程式碼會更易讀。 以下，筆者就以一個模擬報表生成的應用，去解釋如何設計可以即時回傳的 API。 source code: spring-boot-web-api-async ReportController.java 詳細解析 假設我們有一個 ReportController，它負責處理與報告生成相關的 HTTP 請求，它提供三個核心 API 端點。 啟動報告生成端點 @PostMapping("/reportJob/create") public ResponseEntity createJob() { String uuid = String.format("%d_%s", (new Date()).getTime(), UUID.randomUUID().toString()); CompletableFuture.runAsync(() -> { try { orderStatus.put(uuid, PROCESSING); Thread.sleep(10000); // 10-second simulated delay reportService.genAndSaveReport(uuid); orderStatus.put(uuid, COMPLETED); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } }); return ResponseEntity .accepted() .header(HttpHeaders.LOCATION, "/reportJob/status/" + uuid) .body(Map.of("uuid", uuid, "status api", "/api/reportJob/status/" + uuid, "download api", "/api/reportJob/download/" + uuid)); } 運作原理： 立即生成唯一的 uuid 來標識這次任務 在 CompletableFuture.runAsync 運行長時間的操作。 API 本身即時回傳了 HTTP 202 (Accepted) 狀態，告訴客戶端請求已被接受但尚未完成 在回傳的結果中，還有提示可以查詢狀態和查詢結果的API。 這種設計避免了 HTTP Gateway Timeout，因為回應是即時的 。 檢查進度端點 @GetMapping("/reportJob/status/{uuid}") public ResponseEntity getStatus(@PathVariable("uuid") String uuid) { String status = orderStatus.get(uuid); if (status == null) return ResponseEntity.notFound().build(); if (COMPLETED.equals(status)) { // return ResponseEntity.status(HttpStatus.SEE_OTHER) return ResponseEntity.ok() .header(HttpHeaders.LOCATION, "/api/reportJob/download/" + uuid) .body(Map.of("status", COMPLETED)); } return ResponseEntity.status(HttpStatus.ACCEPTED) .body(Map.of("status", PROCESSING)); } } 單純以 map orderStatus.get(uuid) 查看狀態結果。這個map 必需是多線程下使用還是安全的 (ConcurrentHashMap)。 下載結果端點 @GetMapping("reportJob/download/{uuid}") public ResponseEntity download(@PathVariable("uuid") String uuid) { String status = orderStatus.get(uuid); if (status == null || !COMPLETED.equals(status)) { return ResponseEntity.notFound().build(); } else { // 下載檔案 } } } 如果大家並不計較是否需要重做失敗的請求，這個例子已經可以簡單地達到即時異步回傳的效果。如果大家還需求考慮請求是否有效完成，就需要用到 message queue 或其他 job server ，這就不是同一個網頁應用的操作範圍。 Reference source code: spring-boot-web-api-async Building a Long-Running Async REST API in Spring Boot (with 202 + 303 Status Codes)

高達模型，不噴塗還有什麼選擇？

手機‧電玩
MacauYeah・2025-10-09

之前筆者就高達模型中，籠統地比較不同的1/144比例產品。現在筆者也正式入手更多不同的系列，看看有沒有哪些適合不同需求的玩家。 SD系列：Mobile Join Gundam 明盒盒蛋，拼裝模型，但不需要剪鉗也可以隨手取件。要補色、滲線或進行一步加工制作。優點是可動性高，官方有提供補色貼紙，但距離足夠分色，還是有一段距離。 筆者並不在意它的分色不完美，以這個不足百元的商品來講，可動性足夠讓筆者快樂一個下午。 SD系列：FW Gundam Converge 明盒盒蛋，有少量件需要拼裝，大部份都已經有預塗裝。因為制作比較精緻，人氣商品比MJG會再貴一點。但可動度就很低，幾乎只有手臂、手碗、頭的平轉，腿腰不可動。筆者購入這個系列的原因，主要是當時已經無力再自行塗裝，把它當完成品直接買回來當擺設，也是一番享受。 兩者二選一的話，筆者更偏好MJG，因為有可動性，強行把玩也勉強可玩，一起擺場景也更耐玩。而FW的話，它的優勢反而是選擇多，方便整個系列收藏。因為有塗裝，而且有少部份可動，想拍照也不是不可以，耐玩度不高就是了。 FW就筆者跟朋友交流，在另一個系列MSE的出現下，FW似乎不太受樂。不過筆者未入手過MSE，難以作比較。但外觀上，似是MJG的另一個版本，但沒有骨架。

小比例高達的選擇： HG vs RG vs R魂 （MR 魂）

手機‧電玩
MacauYeah・2025-09-29

筆者過往一直就關注高達HG 模型的素組制作，以及把玩相關資訊。而眾所週知，HG的精緻度及可動性，其實都不怎麼，想要美觀，必需要花很多心思去制作才行，想要高可動，也要一定的改制能力。 就以不噴塗的前題下，1/144比例下，除了HG外，我們還有的選項，就是 RG , Robot 魂 和 Metal Robot 魂。而筆者這兩三年，都陸逐有入一些近期的貨，可以分享一下對比。我們就先各個系列對比 HG 作一些分享，最後再分情境做個綜合評價。 RG vs HG 只要你有薄刃剪 + 滲線 + 貼紙，你就會得到一台可以吊打HG的高細節高達模型。貼紙是套件內附送的，只要把貼紙好好貼完，什麼水口阿，都可以無視。這是最最最大的優勢。 缺點就是你的選擇不多，而且高達套件都有軟骨問題。不把玩，全部罰企，是可以接受的。高強度打把，最好選擇RG25號以後的作品，把玩時也要格外小心，因為真的易壞。 Robot 魂 vs HG 課金取得官方代工，買回來就可以即時把玩。最美好的部份是可動性一般比同期HG高（不必然）。手型、特效件也比HG 多。筆者認為開箱即玩擺POSE，是它的最大價值，所買回來一定要開箱把玩、拍照，不然發揮不出它的性價比。 雖然R魂可以視為官方代工，但這個代工的細節並不多，並不包括滲線和貼紙，所以你想拍一些近鏡的大頭相，還是太過素。有需要還是可以自行刻線或另購水貼。 Metal Robot 魂 vs HG MR魂，其實就是R魂的升級版，部份關節或內構，以合成金屬制作，強度會再早高一級。大家可以視為課金取得更高級的代工，外表雖然無淺線刻線，但塗裝+移制技術，已足夠表出現細節等。拿在手上，就有一種珍品的感覺。 MR魂好像有錢就什麼都解決了一樣，但其實不是。它的可動性，其實不太特別突出，而且會有掉件問題。筆者入手的兩款通販MR魂，都有群甲容易掉落的問題。所以錢只是花了在塗裝和用料上，把玩體驗可能不比R魂強（特效件少很多） 綜合情境 何時選擇HG: 款色限定，因為HG的款色夠多，其他魂系並一定有推出。HG可能是某些機體的唯一選擇。想爽玩，想好看，一定要有些動手能力。 何時選擇RG: 如果你覺得帥就完事，但又不想花太多錢和時間，那麼RG就是你的好朋友。只要細心對著說明書拼裝，貼上貼紙，就不用再花心思了。 何時選擇R魂: 對於把現有要求的朋友，可以選這個系列。有空就把來扭一扭，做個情境，是何其狀觀的一件事。 何時選擇MR魂: 不想動手拼裝，又想帥，但把玩時間都沒有的朋友，可以選這個。開箱上支架，選一個固定的姿勢，長放飾櫃，那是最簡單也最優美的一件事。

git submodule 的那些坑

科技新知
MacauYeah・2025-09-26

submodule 設定 有些時候，我們並不想追蹤submodule的預設分支。對於初次新增時，我們可以 git submodule add -b YOUR_BRANCH REPO_URL_OR_RELATIVE_REPO_PATH git submodule add -b feature/devcontainer https://github.com/macauyeah/spring-boot-multiple-datasource.git git submodule add -b feature/devcontainer ../spring-boot-multiple-datasource 若在初始化後期，想改branch，可以直接修改設定檔。(首次做，還是建議使用指令方式加入，因為第一次總要把submodule整個歷史記錄取下來。) # file .gitmodules [submodule "spring-boot-multiple-datasource"] path = spring-boot-multiple-datasource url = https://github.com/macauyeah/spring-boot-multiple-datasource.git branch = YOUR_BRANCH 關於上述 url 的部份，如果是公開的倉庫，當然可以以完整的方式存取。例如你可以直寫 url = https://github.com/macauyeah/spring-boot-multiple-datasource.git。 若為私有倉庫，道理上要本機有權限存取才行，對於持續整合/持續部署就有些麻煩。正常解決方向就是 CI Server 有齊所有倉庫的存取權限，具體要根據不同 CI Server 的設定，有時候還要跨 Docker 的方式去接入。那是有夠麻煩的一件事。但若果 main module 與 sub module 剛好為同一個倉，我們也可以使用相對路勁來解決。 # file .gitmodules [submodule "spring-boot-multiple-datasource"] path = spring-boot-multiple-datasource url = ../spring-boot-multiple-datasource.git branch = YOUR_BRANCH 但這是有代價的，我們在本地 checkout 時，也必需要模疑類似的文件夾架構，也就是 sub module 也要獨立 checkout 。

spring data 關聯型態 02 補充更新

科技新知
MacauYeah・2025-09-18

前述有在介紹 spring data relation 的 @OneToMany 的 CascadeType.REMOVE , 有些 hibernate 的行為還是沒有弄清楚 (原文連結 https://lifemag.cyberctm.com/zh_TW/blog/macauyeah/14226）。經過一段時間候，筆者也有新的認知，所以就重新更新一次這部份。 我們在 parent, child 做關聯時，不能偷懶只在 child 更新，不然的話，在同一個 transaction 內進行刪除操作 ，就會出事。在處理 @OneToMany 關係時，必需要經過 collection add remove ，讓 parent 和 child 一起更新。例如下例 code @OneToMany 需要配合 collection add remove 一起使用（this.books.add(book);），不能只做一邊(book.setAuthor(author);)，不然就會出現InvalidDataAccessApiUsageException。這似乎和 hibernate 的狀態有關，只有經過 collection add remove ，hibernate proxy 才會正確反映未來的 db 狀況。特別在某些時候，例如是記有 @Transactional 時，hibernate 似乎不會每次都會真的訪問 db ，如果要準確關聯狀態，就要經過 collection add remove 去更新 proxy。 CascadeType.REMOVE, orphanRemoval = true 在 collection add remove 都有相同效果。

Docker Swarm - Private Registry 私有影像倉庫

科技新知
MacauYeah・2025-09-10

在構建投産環境時，如果 server 群沒有互聯網，又或對私隱很有要求，需要自建一個最簡單的 registry ，可以用這個。當然，那台機第一次必需經互聯網。架起後就可以斷網，並由其他 client 提送新的 registry image更新。 Registry Server 起動方式 最簡單的起動方式，但什麼都不設定。 docker run -d -p 5000:5000 --name registry registry:3 若想要加入 SSL，讓你的 client 不會認為它是不安全的 registry ，最簡易可以寫成 docker compose, 由 docker compose up -d 執行。 # docker-compose.yml registry: restart: always image: registry:3 ports: - 5000:5000 environment: REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt REGISTRY_HTTP_TLS_KEY: /certs/domain.key volumes: - /path/data:/var/lib/registry - /path/certs:/certs 上述的 environment 中，有條件的話，還請設定需要登入才能訪問限制。最簡單，可以使用 apache http header 驗證方式。 # docker-compose.yml registry: restart: always image: registry:3 ports: - 5000:5000 environment: REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt REGISTRY_HTTP_TLS_KEY: /certs/domain.key + REGISTRY_AUTH: htpasswd + REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd + REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm volumes: - /path/data:/var/lib/registry - /path/certs:/certs + - /path/auth:/auth REGISTRY_AUTH, REGISTRY_AUTH_HTPASSWD_PATH, REGISTRY_AUTH_HTPASSWD_REALM 的值照抄就好，然後/path/auth/htpasswd 就需要以 htpasswd 的格式提供內容 apache password_encryptions。即是以下那個樣子 USERNAME_1:BCRYPT_HASH_1 USERNAME_2:BCRYPT_HASH_2 USERNAME_3:BCRYPT_HASH_3 Client 連線方式 一切都設定好後，在 client 端，就可以登入並推送你的 image，(題外話，cli登入的都是以明文的方式存在電腦中，所以不要隨便在公開的地方存入自己的帳號) # login docker login YOUR_DOMAIN:5000 # try re-upload image docker image tag registry:3 YOUR_DOMAIN:5000/registry:3 docker image push YOUR_DOMAIN:5000/registry:3 如果 server 端沒有提供SSL，那麼 client 就只能設定 http 的不安全連線。 https://distribution.github.io/distribution/about/insecure/ 修改 client 端的 /etc/docker/daemon.json (Windows Docker Desktop請經 Gui修改)，然後重啟 client 端的 docker { "insecure-registries" : ["YOUR_DOMAIN:5000"] } Registry Server 維護 - Garbage collection 垃圾回收 當我們設立了自己的 Registry 倉庫之後，少不免就是要維護硬碟的用量。很多過期的 Image ，沒有需要，那就手動刪除，然後進行 Garbage collection (垃圾回收)。另一種情況，就如前述教學中，大家使用統一版本號，例如 latest ，表面上看似只有一個 tag ，但其實底下可能已經藏有多個不同的版本，也需要經過Garbage collection來清理空間。 因為回收過程比較危險，所以官方並不建議自動做，以下就簡單講講為了做刪除和回收，設定檔要怎樣改。為方便改設定，我們更新 docker compose yaml 檔，把 server config 都帶到 container 外面。 registry: restart: always image: registry:3 ports: - 5000:5000 environment: REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt REGISTRY_HTTP_TLS_KEY: /certs/domain.key REGISTRY_AUTH: htpasswd REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm volumes: - /path/data:/var/lib/registry - /path/certs:/certs - /path/auth:/auth + - /path/config.yml:/etc/distribution/config.yml config.yml 就如下所示，為了提供 API 刪除 image 的可能，storage.delete.enbled 要為 true，又為著之後進行回收時，可以避免有人於回收中途上載，所以預先加入 storage.maintenance.readonly.enabled 的控制項。回收之前要把readonly改為true，回收後再調為false。 每次修改完，記得重啟一下 docker service 。 storage: filesystem: rootdirectory: /var/lib/registry delete: enabled: true maintenance: readonly: enabled: false Garbage collection 指令 # inside container # bin/registry garbage-collect [--dry-run] [--delete-untagged] [--quiet] /path/to/config.yml bin/registry garbage-collect --delete-untagged=true /etc/docker/registry/config.yml # outside container, at host level docker exec -it YOUR_CONATINER_NAME bin/registry garbage-collect --delete-untagged=true /etc/docker/registry/config.yml

HG維爾達制作心得分享

手機‧電玩
MacauYeah・2025-09-08

第一次組鐵血系列，骨架看去很好，玩起來則很懼怕。 造型上，沒有Seed系的重背包，是穩定站立的根源，這點我很喜歡。也因為沒有背包，外型上就更沒W系，Seed系的三角肩，整體很有UC那種精練感。 水口: 沒有全修水口，就只有修外甲、部份骨架的明顯之處。修水口後，以水性馬克筆重塗遮蓋。 補色: 按照官點補色，主要是深灰、紅色及骨架少量銀色。另外就是因為遮水口的原因塗了不少天藍色。 滲線: 0.1刻刀加深高低差，再加黑色水性滲線液。

升級 Spring Boot WebClient SSL (Reactor Netty 1.2.6)：重新配置 SSL 設定

科技新知
MacauYeah・2025-08-27

因為SSL provider 更新了的關係，好多 HttpClient / WebClient 設定SSL的部份都要重寫以免出現 deprecated 問題 reactor.netty.http.client.HttpClient 在 1.0.x, 中可以這樣自行設定SSL逾時的部份，但當中的spec.sslContext().defaultConfiguration 在新版本，例如1.1.x後就會出現 deprecated。 // deprecated version HttpClient.create() .secure(spec -> spec.sslContext(SslContextBuilder.forClient()) .defaultConfiguration(SslProvider.DefaultConfigurationType.TCP) .handshakeTimeout(Duration.ofSeconds(30)) .closeNotifyFlushTimeout(Duration.ofSeconds(10)) .closeNotifyReadTimeout(Duration.ofSeconds(10))); 觀看各大網站，都未有更新，唯有自行研究官方說明。 筆者撰寫本文的時候，netty 發行版本為 1.2.6， 1.3.0 還里程碑(M6)的階段。所有參考皆來自1.2.6版本，實際上我們要使用新的後綴為ContextSpec類，看Class名應該有分http 1.1， 2， 3的版本，筆者就試用最基本的http 1.1。Http11SslContextSpec, (有條件的朋友可以試用Http2SslContextSpec, Http3SslContextSpec) import reactor.netty.http.Http11SslContextSpec; import reactor.netty.http.client.HttpClient; import java.time.Duration; import org.springframework.web.reactive.function.client.WebClient; import org.springframework.http.client.reactive.ReactorClientHttpConnector; //... Http11SslContextSpec http11SslContextSpec = Http11SslContextSpec.forClient(); HttpClient httpClient = HttpClient.create() .secure(spec -> spec.sslContext(http11SslContextSpec) .handshakeTimeout(Duration.ofSeconds(30)) .closeNotifyFlushTimeout(Duration.ofSeconds(10)) .closeNotifyReadTimeout(Duration.ofSeconds(10))); WebClient webClient = WebClient.builder().clientConnector(new ReactorClientHttpConnector(httpClient)) .build(); //... 雖然這個寫法來看netty 1.2.6，但似乎1.1.x 通用。大家有需要可以交互測試一下。 Reference netty 1.2.6 http-client-timeout 的設定 netty 1.1.30 timeout-configuration 的設定 netty 1.2.6 java api doc netty release version 更多筆者的程式開發分享，見請 github

Spring Boot Web App 更新期間的維護模式：從唯讀到全鎖的解決方案

科技新知
MacauYeah・2025-08-25

在營運 Web App 的時候，雖然我們有 Docker / K8s 可以滾動更新，但難保用戶在更新的過程中，有一半訪問去到了舊版，另一半去了新版。如果可以，Web App 本身自帶維護模式，可以自我判斷什麼時候應該忽略新的訪問，當然最好。但要做到這一點，前期需要很多規劃。狠心一點，可以直接關掉對外的服務，讓用戶無法訪問。 但在另一些情況下，例如升級/搬遷的情況，下線時間比較長，完全關掉服務並不是一個很好的方向，我們至少還可以提供唯讀的選擇。而且這個可以從資料庫出發，讓 Web App 少處理一點邏輯。 如果 Web App 背後的資料庫是 MSSQL 或 MySQL，唯讀這件事應該是簡單的，只要你把 service account 的權限改變就好。但如果你用Oracle，就要想想辦法。 筆者想到的方法，暫時有兩個。第一個就需要大家寫寫 Script ，一口氣把所有 Table 給鎖起來。例如: 第二個，就是生成一個新的唯讀 User schema，給他所有Select的權限。然後更新 Web App 使用那個唯讀 User schema存取資料。 兩個方法有什麼差異呢？ 前者就全部鎖起來，沒有任何一個資料庫用戶可以改寫資料。如果你的業務沒有差異性，全部一起封起來就完事。但如果你只想 Web App 轉成唯讀，但其他背景程式還可以執行更新。那你就只能用後者了。但後著也不是百分百的完全無痛，至少你 Web App 要支援登入與操作的 Schema分離。 例如用Spring boot JPA的話，可以在 application.properties 可以讓登入及操作的Schema不一樣。 spring.datasource.username=READ_ONLY_USER spring.jpa.properties.hibernate.default_schema=ORIGINAL_SCHEMA 又或者在 java 層面指定。 @Table(schema = "ORIGINAL_SCHEMA") 這看上去，是很有彈性的。但其實也是有些局限。如果你本來的JPA有寫特制的 JPQL 或 Raw Query，又或者你在Java層面加了 @Subselect，由於這些都是程式原作者所 hard code 的，JPA沒法幫你改寫。改來改去，可能還是前述寫Script的方法，一口氣把所有 Table 給鎖起來實際一些。 Reference 更多筆者的程式開發分享，見請 github

Galera 4 (Mariadb cluster) 的冷開機

科技新知
MacauYeah・2025-08-20

前次我們介紹了 Galera 4 在Ubuntu 24的架設方式，這次我們來補充一個最常見的問題Cold Start 冷開機 cold start 平常， Cluster 中只有其中一個 node 需要更新重啟，基本上所有節點回覆正常後，都可以互相通訊。而有些情況，例如斷電問題，需要所有節點全數關機，那麼 Galera cluster 就需要一定的方式重啟系統。那是一些狀態的保護機制，因為在全關機後再同步，系統不知道哪台機才有最新的狀態，它也不敢貿然同步(因為正常使用下， Galera cluster 只有兩台機也會開步)。所以需要人手介入，指定以某台機作為 cluster 的起始點。 舉個最簡單的例子，前述三台機 pocdbnode3 ， pocdbnode2 ， pocdbnode1 順序關閉，那麼 pocdbnode1 應該就會有最新的資訊。 在ubuntu中，可以查看 /var/lib/mysql/grastate.dat 中的 safe_to_bootstrap:是否為1。如果是1，代表當初它有最後的 transaction ，以它為起始點重新起 cluster。 $ cat /var/lib/mysql/grastate.dat # GALERA saved state version: 2.1 uuid: 0c38b6dd-7bdb-11f0-a4dd-1f4be36a6ea9 seqno: -1 safe_to_bootstrap: 1 我們使用galera_recovery, galera_new_cluster, 就可以把該機器重新救起mariadb process。 $ galera_recovery WSREP: Recovered position 0c38b6dd-7bdb-11f0-a4dd-1f4be36a6ea9:11 --wsrep_start_position=0c38b6dd-7bdb-11f0-a4dd-1f4be36a6ea9:11 $ galera_new_cluster 然後其餘兩個 node 可以直接重啟 mariadb 服務 # node 2 $ systemctl start mariadb # node 3 $ systemctl start mariadb Reference Getting Started with MariaDB Galera Cluster 官方文件 How to Set up MariaDB Galera Clusters on Ubuntu 22.04 How to Bootstrap MySQL or MariaDB Galera Cluster – Updated : 還有比較複雜的救機狀況，例如:safe_to_bootstrap全為0，即是可能是全部node都沒有好好地關掉，就掛了。大家有需要可以看看這個link的解決

Spring boot 10 - openapi 生成器 - spring boot java client

科技新知
MacauYeah・2025-08-19

之前我們在介紹Spring Boot Web 調試工具 ，就試安裝 openapi 相關的元件。其實 openapi 並不單是為了提供 swagger 測試介面，它主要是提供一個描述的方式，讓我們針對一個特定 openapi 文件，生成對應的 api server 或 api client 接口。也就是，如果 server 方有提供該文件，道理上可以經 openapi 的工具，生成一個可以直接訪問 server 的 client library。本節，可以沿用之前的 spring boot web api doc ，為它產生一個client library 作為實驗。 在生成 client library 之前，我們還需要一個工具 openapi-generator-cli 。最簡單的取得方式，就是經過 npm ， 在你需要生成 client library 的專案中，安裝你需要的 openapi-generator-cli 版本。 npm install @openapitools/openapi-generator-cli 那怕你不是使用 nodejs 作為開發，也可以經過這個方法安裝。它只提供使用 cmd 指令的捷徑。 生成 Java Client Library 我們先把 backend server 起好 cd somewhere && mvn spring-boot:run，然後使用 openapi-generator-cli 去生成以 java spring boot 3 為底的 client library 。 npx openapi-generator-cli generate \ -i http://localhost:8080/v3/api-docs \ --api-package io.github.macauyeah.springboot.tutorial.openapiclient.api \ --model-package io.github.macauyeah.springboot.tutorial.openapiclient.model \ --invoker-package io.github.macauyeah.springboot.tutorial.openapiclient.invoker \ --group-id io.github.macauyeah.springboot.tutorial \ --artifact-id spring-boot-web-api-open-api-client \ --artifact-version 0.0.1-SNAPSHOT \ -g java \ -p useJakartaEe=true \ -p useSpringBoot3=true \ --library webclient \ -o spring-boot-web-api-open-api-client 生成的 source code 就像是 spring-boot-web-api-open-api-client ，具體的使用方式，可以看看測試用例 ApiControllerApiTest.java private final ApiControllerApi api = new ApiControllerApi(); @Test public void postDateQueryTest() { // default call ApiDateRequest apiDateRequest = new ApiDateRequest(); apiDateRequest.setInputDate(OffsetDateTime.now()); LOG.debug("default web client postDateQuery:{}", api.postDateQuery(apiDateRequest).block()); // replace webClient in ApiClient if you have special auth config on // webClient, you can also change basePath during new obj creation ObjectMapper mapper = new ObjectMapper(); mapper.setDateFormat(new SimpleDateFormat()); mapper.registerModule(new JavaTimeModule()); WebClient webClient = WebClient.builder() .codecs(configurer -> { configurer.defaultCodecs().jackson2JsonDecoder(new Jackson2JsonDecoder(mapper)); configurer.defaultCodecs().jackson2JsonEncoder(new Jackson2JsonEncoder(mapper)); }) .build(); ApiControllerApi api2 = new ApiControllerApi( new ApiClient(webClient) .setBasePath("http://localhost:8080/")); LOG.debug("create api2 by local web client postDateQuery:{}", api2.postDateQuery(apiDateRequest).block()); // use webClient directly String response = webClient.post().uri("http://localhost:8080/api/record").bodyValue(apiDateRequest).retrieve() .bodyToMono(String.class).block(); LOG.debug("request by local web client postDateQuery:{}", response); } 上述例子中，如果大家沒有任何特殊要求，其實經過 api.postDateQuery(apiDateRequest).block() 就完成了。有需要改 api endpoint 的，只要生成新的 ApiClient 並設定 basePath new ApiClient().setBasePath("XXXXXX") 就好。真的要加入更多權限設定，就需要生成新的 ApiClient 並設定 webClient new ApiClient(webClient) 這個生成的 Java Client Library 道理上還是要經過 maven 等打包，變成 jar 檔，才能被其他 Java 專案所引用。筆者就建議大家直接把成生的視為獨立的 module (sub module) 存放，其他專案就以 maven dependency 的方式引用。想要混合現有專案，動態生成專案內某些 java package，暫時不太可行。因為它也有大量的 dependency ，交由 openapi-generator-cli 自己管理會比較好，它們升級時，你也可以完整升級。 openapi-generator-cli https://github.com/OpenAPITools/openapi-generator-cli spring-boot-web-api-open-api-client

重入膠坑 11 ｜素組黨的水口極限

手機‧電玩
MacauYeah・2025-08-09

陸逐地，筆者分享了一些高達模型回鍋的心得近一年，素組的手法實驗也做得七七八八了，再推過，就是向噴塗進發。 素組主要是考慮水口處理和補色的問題，而水口更是入門模型的重症。筆者就再在這一篇做個水口處理的總結，比較不同的處理方式的效果。 神剪 最簡單的方式。做MG的話很夠用，不過做HG，有些水口的位置很奇怪，看著就難受，而且會影響補色。 神剪+打磨(低目數至高目數砂紙) 有效消除明顯水口的方式，最後只會留有白點或深色的一點。看個人需求，是否可以無視那「一點」。另外因為打磨量多，塵土飛揚，需要注意環境影響。 神剪+打磨(低目數砂紙+筆刀水平刮) 能除去水口，但平面不平整，很多時會見到刮痕，比較不可能無視。筆刀刮出來的碎屑比較大粒，沒有那麼大塵。 神剪+Marker補色遮蓋 不能遮蓋水口，因為有高低面，造成積漆，所以會很奇怪。跟只有神剪的效果差不多，非常不推薦。 神剪+打磨(低目數至高目數砂紙)+消光 更大程度模糊水口剩下的那「一點」。工作量雖多，但效果算是上好。 神剪+打磨(低目數砂紙+筆刀)+消光 水口、刮痕會被模糊，正面看就看不到刮痕，側看還是很明顯。 神剪+打磨(低目數砂紙+筆刀)+Marker補色遮蓋 因為筆塗漆面比較厚，水口及筆刀的刮痕基本都可以被覆蓋，平面不平整的問題就沒有辦法解決。另外筆塗會引入筆痕、塗裝出界、刮漆的問題。 神剪+打磨(低目數砂紙+筆刀)+Marker補色遮蓋+保護漆 保護漆可以減少前述刮漆問題，仍需無視平面不平整的問題。如果想更進一步防止刮漆，需要向底灰進發。底灰已超出了素組的範圍，就不作太多描述。 神剪+打磨(低目數至高目數砂紙)+Marker補色遮蓋+保護漆 理論上是最優解，工作量也是最多的。 該選擇什麼？ 初入門，可能「神剪」就夠。因為工作量最少，效果最顯注。 進一步就是「神剪+打磨（低目數+筆刀）」，優點亦是工作量沒有多很多。同時可以挑戰刻線滲線，工具和流程也沒有很大衝突。 實在像筆者那般，接受不了那「一點」，就「神剪+打磨(低目數+筆刀)+Marker補色遮蓋。筆刀比高目數打磨省時，Marker也可以完全遮了那「一點」。 至於為何不用消光漆呢？ 首先，噴鑵消光的成本是很高的，想好好地逐個部位噴，很快就會用完。 第二，消光的作用是讓高達模型的那層膠面不再發生，看起來沒有那麼玩具感。而我們前述經打磨和補色（什至是色差補色），原本顏色已經豐富好多，使用消光漆的差異唔太明顯。 第三，就是後期修補更難，消光漆想想地清理，是非常之煩。一定要確保各項工序做完，例如修正出界、滲線不乾淨、重滲線問題，再去上消光漆。不過如果全部做足了以後，可能已經沒有很想消光的必要。

和模線-TASTIER-塔斯提爾

手機‧電玩
MacauYeah・2025-07-23

繼上次組了一次國產摩動核之後，再次挑戰國產原創品牌-「和模線-TASTIER-塔斯提爾」 不得不說，這次體驗好很多。優勝於摩動核的地方主要分為： 水口位置。因為不是全部隱水口，水口的位置 沒有那麼刁鑽，比較易用剪鉗處理。 外甲設計。沒有那個動不動就出尖刺的國型，把玩起來舒服很多。整體做型也以仿生機甲為題，有一份清新感。 組合流暢道。因為沒有合金體架，沒有地方出過大力金剛指的需要。因為它沒有背包負擔，所以沒有合金配重，其實也OK。 筆者亦分享一下自制的取件表，方便需要批量後制的朋友們。但件量真的多，筆者就沒有挑戰後制了，有追求的朋友可以試試看。 最後附上筆者的一些造型圖。貼近人型的比例，再加上什少外甲的干涉，好多POSE都易攪，多角度也不會不自然。

生活AI 應用筆記

科技新知
MacauYeah・2025-07-22

上週六（7月19日），筆者參加了聖公會的一門講座「AI時代，父母的教養實戰新教程」，學習如何利用AI輔助小朋友的教育。雖然課題如此，但課堂還是以感受AI的使用方式為主，之後大家就好好利用AI這個知識庫去激發新思維。課堂上，文字、語音、動畫都有示範，但筆者感受到文字AI的部分最為深刻。 在過去一兩年，筆者曾略微使用AI，但即使在DeepSeek出現後，筆者仍覺得幫助有限。這主要是因為筆者身處科技行業，AI給出的答案不夠精準，難以協助開發，還可能導致一堆無法延續的結果，因此筆者甚少使用。然而，上課的主題並非針對本業使用AI，而是探討如何利用AI為生活注入更多新感受。 AI或許無法取代專業，但可以幫助你引入跨界元素，讓思考模式或你的作品更加多樣化。課堂中，學員將自己創作的家書放入AI，請它協助轉換成不同年齡層的人用詞、改編為劇本或變成辯論議題等。當然，並非每個方向都能產生合理的結果，例如家書轉為辯論，明顯會顯得不合適。但由於轉換的成本低，你可以透過少量提詞，得到多樣不同的呈現效果，激發新的思維。這就像在創作前，你可能會參考大量同類型的作品，去取得靈感。 筆者也簡單分享一些使用文字AI創作的方向，希望大家能有所收穫。 首先，準備好自己的原稿，這個原稿必須是由自己親自起草的，而非AI生成的主題方向。起草時，不必過於拘泥於前後文法，只需有一個大概方向即可。 將原稿交給AI，請它幫忙修改。AI會協助你修正一些口語或錯字問題。 嘗試請AI給你一些建議，或者請它幫你補充段落。筆者認為，請AI給建議會更好一些，因為有時補充段落可能會顯得過於機械。 除此之外，文字AI在日常生活中還做得不錯的實例 整理文章重點，重新以不同的方式演繹 整埋文章重點，筆者在大學的教育中，就經常看到以條列重點去取得原本書的教學方式。所以針對中小學教育，或新知識的學習，都可以試試用AI來整理大意，提升學習效率。 更強的是，如果你還是看不懂，可以叫AI以更多例子，深一點或淺一點去解釋一次。 禮物準備 有時物輕情義重，如果你身邊的親友很重儀式感，那麼使用AI的搜集及變化能力來幫你多樣化禮物的準備，相信可能為你加入更多新元素。 計劃旅行 計劃旅行，過去一般都參考他人的行程分享。過去就一篇一篇地逐篇閱讀，個人歸納。現在你可以先問AI，再去覆核。過去自行搜尋的方式，可能會被一些旅遊網站的文章所佔據，而現在改用AI，配合不同的提詞（prompt），你還可以多一些不同的參考角度。 註：本文僅使用AI修正用字，並未生成任何插畫或議題。

Docker 101 - 為何要做成Docker (Container - 容器化)

科技新知
MacauYeah・2025-07-21

筆者更新了之前的Docker入門筆記（https://github.com/macauyeah/VMDockerNotes/blob/main/DockerConcept101CN.md），順便補充了一些內容。如果各位讀者還在糾結要不要進行容器化，可以看看這些特性有沒有讓你心動。 Container - 容器化的便利 1. 做到隔離效果 傳統上，同一機器安裝不同的 lib / dependency ，可能出現衝突。在 docker 的環境下，不同 container 之間可以隔離開，除了是網路之間出現引用關係的衝突外，動態庫的衝突就沒有見過。一般處理好 Persistent Volume 的考量，單機下是沒有什麼問題的。 2. 遷移的過程比較簡單 傳統上，要把程式從一台機器搬到另一台機器，要預先安裝好相關的 lib / dependency 。但使用 docker / container 後，只要 docker 版本相容就好。docker image 本身，就已包括所有的 lib / dependency 。另一個常見的傳統問題，就是 Linux 檔案的擁有權問題，特殊情況下，新機同一個 user 的 ID 編號也不一樣，可能要手動恢復權限。如果是 container 的 bind mount 檔案，只要使用 tar command （`tar --same-owner -xvf file.tar`）保留權限解壓就好。 3. 垂直水平擴容 因為有隔離及遷移方便的優勢，原本的機器達到上限，可以隨時換到其他機器上，修改對應的用戶入口就可以了（或更改DNS，可以更無縫連接）。一台機器不夠，亦可以多台機器一起來。即使不使用 docker swarm / k8s 方案，有傳統的 proxy gateway 再加單機的 docker ，就可以做到分流的效果。 當然使用 docker swarm / k8s 才是正解，可以更簡化 proxy gateway 的設定。而傳統的分佈式問題，例如 Share Storage 等，其實就沒有簡化到，但也沒有增加難度。所以大家若考慮擴容的問題，更適合考慮使用 Container 的方案。 筆者總結這兩三年來的使用經驗，只要大家一直有用開Linux，其實單機容器化不太難，頂多就是配置外置Persistent Volume / Share Storage會帶來不習慣。而大家也可以想，Storage 這問題，是隨時隨地佈署應用程式的不可或缺的思考方式。Docker 沒有帶來更多的麻煩，而是帶來更多標準化的應用，例如傳統的NAS / NFS，也是這個Storage問題的其中一個解法。

MacauYeah

專注於傳統遊戲文化研究的玩家

YouTube https://www.youtube.com/channel/UCIjcCxgxWIqvjRAr0e96uOQ

Facebook https://www.facebook.com/Macau-Yeah-289032771943982/

Twitch https://www.twitch.tv/macauyeah/

Speedrun https://www.speedrun.com/macauyeah