文章列表

Spring Boot 06 - Spring Boot Web 調試工具

科技新知
MacauYeah・2024-08-02

之前兩節,都一直在講怎樣寫code,也介紹了Test Case的好。若為初次接觸,Spring有很多設定需要摸索,若開始時就設定錯誤,對不少人來講都會有很大打擊。在這裏,筆者就介紹一些vscode和spring的工具,可以讓IDE多幫忙一下,減少走歪路的機會。 vscode插件 以下兩個插件,都在於提示用戶設定。 Spring Boot Dashboard (vscjava.vscode-spring-boot-dashboard) 可以那它來運作spring boot app,省去找尋main 位置的麻煩 綜覽整個程式中的所有Bean (Bean是一個很重要的元素,日後會再提及) 若程式為Spring boot web,可以顯示所 http endpoint。 Spring Boot Tools (vmware.vscode-spring-boot) 檢查設定檔的設定值有沒有寫錯 (application*.properties, application*.yml) 綜覽檔案中的有以@為首的與spring相關的元素(檔案很大時就會有用) 可以在IDE運行spring時,查看@元素的bean資訊 (not works ?, 加了actuator也是沒有看見) Spring Initializr(vscjava.vscode-spring-initializr) 經網絡初始化spring 專案的依賴引用設定 Maven for Java (vscjava.vscode-maven) 若大家在使用Spring Initializr時,選取了maven作管理工具,那麼這插件就可以在後續幫忙更新引用。 若專案的Spring 及㡳層引用有變,vscode也需要它來引用更新。 這是java 開發工具包(vscjava)的其中一員,它的其他插件也可以順帶安裝。 調試工具 - open api / swagger-ui 如果我們在開發Web http API ,其實都是為了該某個客戶端使用。但如果該客端明白我們的API該怎樣使用,大家總不會逐個連結,自行編寫使用手冊及範例吧。所以就有了open api 和 swagger-ui 的旦生 。 open api,就是一個公認的使用手冊標準,我們只要在spring-web中加入 springdoc-openapi-starter-webmvc-ui 的程式庫,就可以自動為我們的controller 生成 open api 的說明檔。 更強大的是,這個程式庫可以利用剛生成的open api,配上 swagger-ui ,自動測生一個可供測試的頁面。這個頁面可以供碼農們直接操作,也會產生對應的 curl 指令,讓碼農們可以在任何的主機上重複。這樣,那麼是沒有太多解釋的說明文檔也可以使用。 做法很簡單,在pom.xml中加入依賴。 org.springdoc springdoc-openapi-starter-webmvc-ui 2.5.0 (由於安全性問題,上述程式碼未能完整顯示,請參見文末完成Source Code) 然後我們就可以加入Controller,運行 spring 後,我們可以在 http://localhost:8080/swagger-ui/index.html 找到 swagger 的頁面,然後就可以在 ui 上測試API了。 躲在Proxy背後的 swagger 如果你跟筆者一樣,使用 code-server 或 github codespaces ,你就不能很隨意地連接到 8080 端口。你只能經過Http Proxy去訪問。這樣 open api的原有的設定就不合用了。 這時我們需要自行修改 open api 的 bean,加入我們真正的根路徑。然後筆者使用 code-server,而IDE只會在port 9000上執行,它對外的前置路徑會是 http://localhost:9000/proxy/8080/。 @Bean public OpenAPI springShopOpenAPI() { Server server = new Server(); server.setUrl("http://localhost:9000/proxy/8080/"); return new OpenAPI().servers(List.of(server)); } (由於安全性問題,上述程式碼未能完整顯示,請參見文末完成Source Code) 然後訪問 http://localhost:9000/proxy/8080/swagger-ui/index.html,還會發現 "Failed to load remote configuration." 。但你可以在 "explore" 搜尋欄位內貼上 http://localhost:9000/proxy/8080/v3/api-docs,再一次搜尋檔案,就回復正常了。 註:如果你熟習Nginx這類Reverse Proxy ,你的環境有條件直接修改 Request Header,加入X-Forwarded-*,就不用煩惱寫Bean了,也不用手動在explore裏重新修正api-docs的位置。詳見 https://springdoc.org/index.html#how-can-i-deploy-springdoc-openapi-starter-webmvc-ui-behind-a-reverse-proxy Controller的繼承 Spring Controller的 @ 標記 (Annotation) ,其實支援繼承的。經Spring 生成的 api docs,也有如何效果。例如以下程式碼 public class ParentController { @GetMapping("/postfix") public String postfix(){ return "this is postfix"; } } @RestController @RequestMapping("/api") public class ChildController extends ParentController { @GetMapping("/direct") public String directCall() { return "direct result"; } } (由於安全性問題,上述程式碼未能完整顯示,請參見文末完成Source Code) 在ChildController的實例中,它會有兩個API,分別是 /api/direct /api/prefix 它支援Java Function Overwrite(覆寫),但不能改 @ 標記,以下就是一個錯的例子 @RestController @RequestMapping("/api") public class ChildController extends ParentController { @GetMapping("/Overwrite") // 把這個 @ 行刪了才能正常執行 public String postfix(){ return "this is Overwrite"; } }(由於安全性問題,上述程式碼未能完整顯示,請參見文末完成Source Code) Source Code spring boot web api doc

Swarm mode 上線 4 | IP 設定

科技新知
MacauYeah・2024-07-23

單機模式 IP設定 平常我們自己做測試,網絡功能通常用預設的就好。但當我們的Docker Container需要存取在區域網內的其他資源,避晚IP網段相衝是必需要的事。 大部份情況下,單機Docker使用的預設IP段會是 172.17.0.0/16 172.18.0.0/16 ... 若然現在區域網中,有一段172.18.0.0/24,大家不想Docker踩到其中,可以修改設定檔,加入預設的default-address-pools,以後它就只會從指定的區段使用。 # vim /etc/docker/daemon.json { "default-address-pools": [ { "base": "172.17.0.0/16", "size": 24 }, { "base": "172.19.0.0/16", "size": 24 }, { "base": "172.20.0.0/16", "size": 24 } ] } 其中base,是docker可以操作的總區域,size指的是Docker要自行分段的話,每段的大小是多少,上述的例子,就代表未來可能有以下Docker 網段。 172.17.0.0/24 172.17.1.0/24 ... 172.17.255.0/24 172.19.0.0/24 172.19.1.0/24 ... 172.19.255.0/24 172.20.0.0/24 172.20.1.0/24 ... 172.20.255.0/24 修改完設定後,重啟Docker就會生效。當然,重啟前,先刪除所有不在預設範圍的所有Container。 Swarm模式 IP設定 Swarm模式,與單機差不多,它需要在初始化Swarm就要定義,而且它不能與單機的網段有重疊。單機會預設使用Private IPv4 Class B,Swarm則是預設使用Private IPv4 Class A段,所以我們若就更改,就使用10.x.x.x吧。 docker swarm init --default-addr-pool 10.1.0.0/16 --default-addr-pool-mask-length 24 經上述例子初始化的 ingress 網段,將會是 10.1.0.0/24,隨後每個stack 則會是 10.1.1.0/24 10.1.2.0/24 10.1.3.0/24 重置Swarm 跟單機的情況類似,如果已建立Swarm後才修改網段,還是要整個刪掉重來。 每個節點都要執行以下指令。 docker swarm leave --force 實測swarm leave這個指令也會把所有運行中的stack刪掉。 各節點重新建立swarm # in node 1, init new swarm with new ip docker swarm init --default-addr-pool 10.1.0.0/16 --default-addr-pool-mask-length 24 # in node 1, get new manager token docker swarm join-token manager # in node 2 and node 3, join node 1 with new token docker swarm join --token XXXXX YOUR_NEW_NODE1_IP:2377 雙管齊下 如果大家同想要修定單機及Swarm的網段,還要留意有一個特別的網段docker_gwbridge。它雖然是Swarm的附帶產物,但它則是受單機的網段控制。也就是,如果大家有需要同時修改單機及Swarm的網段,則需要手動刪除Swarm及docker_gwbridge 在每個節點先刪掉舊有的Swarm及docker_gwbridge,並關掉docker docker swarm leave --force docker network rm docker_gwbridge 在每個節點為docker_gwbridge修改設定,然後重起docker # vim /etc/docker/daemon.json { "default-address-pools": [ { "base": "172.17.0.0/16", "size": 24 } ] } 然後像前述一樣,重起Swarm。

Spring Data 關聯型態 01

科技新知
MacauYeah・2024-07-16

筆者身邊的朋友,首次接觸 ORM 的關聯型態時都會覺得很難,筆者自己也是。但在好好地理順它的設計時,就會覺得其實很簡單。 因為篇輻很長,我們先以Code First的角度,先體驗一下ORM程式讀取的便捷性,以及解決一個常見的序列化問題。 雙向存取 例如一個Parent,有好幾個Child @Entity public class Parent { // ... Parent Primay Key @OneToMany(mappedBy="parent") List children = new ArrayList(); // TODO add remove } @Entity public class Child { // ... Child Primay Key @ManyToOne Parent parent; } 上述的寫法很簡潔,ORM會為你自動加入join column,處理關聯的載入。在讀取Parent時,它的所有Children就可以直接在Java層面讀取,在讀取Child時,它的Parent也隨時取得。也就是,開發人員只要經SQL準備其中一方的資料,另一方並不需要手動準備,它就可以自動按需載入。 RESTFul API 坑-雙向存取 Spring Data在Java層面的雙向存取,已經做到很方便。但經常坑到我們的是Spring Data與RESTFul API的混合應用。當我們嘗試經API回傳我們的Parent Json時,API會很聰明地把關聯的Children也變成Json回傳。但他也會把child中的parent不斷重複變成json,變成無限輪迴。 坊間有兩種不同的解決方案,可以防止無限輪迴。 讓Json可以認得已經序列化的元素。@JsonIdentityInfo 讓Json只可以單向序列化(serialization)。@JsonManagedReference, @JsonBackReference, @JsonIgnore 筆者兩個方向都試過,但首個方法並不通用,至少它不能算是一般常見的無腦Json結構。它需要伺服器、客戶端都懂這如何經IdentityInfo認得重複出現的元素。 而單向序列化,是筆者現時的通用解。在設計RESTFul READ API時,筆者就會決定到底是Parent自動回傳Child,還是Child自動回傳Parent。決策的考慮因素,主要在於是否可以簡化Client的API調用次數。通常從Parent出發,自動回傳Child,可以節省API調用。但如果是選項性的結果(List of Value),就倒過來。有時候,遇著API需要雙向設計,就只好自己設計DTO資料傳輸對象 (Data transfer object, DTO)。 例如Parent API,就原封不動回傳原本的元素 @Entity public class Parent{ // ... Parent Primay Key @OneToMany(mappedBy="parent") List children = new ArrayList(); } @Entity public class Child { // ... Child Primay Key @ManyToOne @JsonIgnore Parent parent; } Child API,就反過來引用。 public class ParentDTO { // ... Parent Other fields except children } public class ChildDTO { ParentDTO parent; // ... Child Other fields } 這種DTO,看起來很麻煩。但其實Spring有提供一個簡便的複制DTO功能,它可以把自動複制兩個class中有同一名稱、同一型別的欄位到另一個class上,不需要逐個欄位明文寫出來。 BeanUtils.copy(child, childDTO); BeanUtils.copy(parent, parentDTO); childDTO.setParent(parentDTO) // 因為child、childDTO中的parent欄位型別不同,BeanUtils.copy會自動忽略,其他欄位就會自動複制。 註: 其實古早的網頁系統設計,DTO的概念一直存取。只是現在RESTFul API的流行,很多框架已經提向便捷的Json轉換。若然平時只需Json單向存取,筆者還是省略DTO的建立。

Docker Image打包建議

科技新知
MacauYeah・2024-07-10

之前筆者有分享過兩個不同的Docker Image打包方式 App直接打包成Image 只把底層程式打包在Image中(例如Tomcat),再用Docker Volume的方式讓Container可以起動App。 筆者就兩種方式做了一個條列式的對比。詳見連結 https://macauyeah.github.io/AProgrammerPrepares/VMDockerNotes/DeployDockerClusterCN.html 因為兩種方式筆者都有實作過,也算用了很段時間,所以也有一些實際經驗可以分享。 如果大家上正式的Docker課程,Docker導師通常會推薦為每個App打包成獨立Image,因為底層程式的Overhead通常不大,例如底層程式是Tomcat、Apache、Nignx這類網頁伺服器,重量級的開銷並不是因為多幾個Web Engine的分身造成,通常都是因為業務本身。但如果你講的底層程式是資料庫等的大型程式,才可能會有明顯的差異。 但實務上的建議,就是必需考慮自身的經驗,到底那個方案自己比較有把握。獨立打包App,在正式環境也需要考慮跟蹤問題的情況,多個不同App要溝通,也是了解Container網絡。如果打包底層程式,所有App都可以當成是本機下運行,更有信心追蹤問題,也是一個很好的出發點,到了有需要彈性改變不同App的需要,才轉向獨立打包的做法。 筆者最初也是走這個打包底層程式的方向,到了自己有信心試用Docker Swarm,才走向獨立打包的做法。筆者親身經驗,因為到了Docker Swarm,網段會變得暴增,這跟公司現有的內部網絡相衝的機會就會變多。在Swarm起立初時,筆者並沒有意識到這件事,所以當初排查問題,也花了一些時間才知道要向網段衝突上著手。 另一個出自Docker導師實務上的建議,就是正式環境中不要做用Docker compose,應該使用Docker Swarm。那怕Swarm只有一個節點,也應該用Swarm,導師的主要理據是Swarm有Rolling Update (滾動更新)的機制。同一個node也可以有多個分身,每個分身輪流更新,就不會出現大中斷的情況。筆者就自身經驗,Tomcat可以同時容納一個App的多個版本,Nginx也有Failover(故障轉移)等,如果你很熟這些功能,不一定要需要靠Swarm去提供。可以按自己步調去慢慢適應。

型別對程式語言的重要性

科技新知
MacauYeah・2024-07-08

JavaScript等程式語言的流行,好大一個原因是因為它很簡潔。而筆者認為,動態語言的特性,即是可以省略型別,是讓它簡潔的一個很大原因。(動態、靜態與強型別、弱型別並一定對等,詳見Ref) 動態語言的特性,就是同一個變數,在不同時候可能代表不同的數據類型,有時候是String,有時候是Integer。所以編寫時,乾脆就不寫數據類型,因為寫了也可能是白寫。 因此初學者並不需要處理大多導入(import)問題,也不用考慮很多compile error問題,至少程式可以運行一半,到了最後出錯的地方才停下,也就是不會因為型別問題而整個程式開不了。 不過筆者在接觸了JavaScript後,始終沒有大量使用。一來因為筆者慣用的Java,有著更大的基礎套件,改用JavaScript未必有優勢。而且動態語言還有一個長久的管理問題,我們該如何知道更新的影響有多大? 測試用例不是萬能藥 有一部份的人認為,動態語言管理難,是因為大家不愛寫測試用例。的確,若然大家寫的測試覆蓋率足夠多,一定可以預先發現問題。但筆者在Java上實踐了寫測試的習慣一段時間,依賴測試報錯,其實也是後知後覺。 IDE的界入 筆者認為,若想好好地管理程式碼,光寫測試是不夠的,我們還需要好好地讓IDE了解我們的程式碼,認它可以很有效地重構我們的程式碼。更強的IDE,還有機會可以提醒我們有一些設計上問題。 老實講,寫Java多的朋友,都可能都知道Intellij Ultimate的名字。筆者試用後,的確很有幫助。相較之下,vscode對於Java的支援,並不十分智能。但這裏筆者還覺得vscode對於java的編寫、重構、測試,在免費的情況下,都已經足夠是足夠佛心。對於網頁應用來講,vscode差的是對javascript的支援。 vscode對javascript的支援有限,其實不能怪它不夠努力。你想多一個免費的IDE怎樣去了解你的javascript程式? 我們連型別都沒有寫出來,它能怎樣推敲? 實時去模擬各種輸入?CPU又會不會耗乾?那麼寫到一半的程式碼又怎樣輸入? 直到最近筆者採用TypeScript之後,筆者看到曙光了 TypeScript - 一個變相的JavaScript的靜態型別 原本的JavaScript其實也有型別的,只是不強制。若想IDE支援,需要以特定型式寫註解。但這樣寫註解,工作量並不比引用靜態型别來得輕鬆。所以最後,筆者還是覺得直接套用TypeScript,讓自己在每一次引用參數,都要好好地先了解函數的輸入輸出型別寫法。 說實在,從JavaScript到TypeScript並不輕鬆。一些原本很無腦的Axios, Promise, Vue語句,TypeScript寫起上來,都變得很複雜。但這個套用,對於IDE來講,真的很大幫忙。它就像突然讀懂了我們的程式一樣,可以跳入跳出,可以知道在多少處被引用。重構也變得更有信心,而不是等待事後測試報錯。 有一點要補充,TypeScript並不像Java那般需要完全預先宣告型別。例如函數的回傳結果,TypeScript就不會強制要求寫出型別,因為它可以有限度地猜得出來。當然,如果大家願意宣告,就更好。 總結 總括來講,型別就像厠所的衛生情況一樣。初期當然什麼都不處理也可以,但越用越久也沒有人理會,大家也不想用下去。若然大家都願意努力維持它的品質,大家會更有意願重複使用。 參考資訊 「靜態型別 vs. 動態型別」與「強型別 vs. 弱型別」 https://blog.tarswork.com/post/programming-language-type-system Typed JavaScript https://depth-first.com/articles/2021/11/03/typed-javascript/

Spring Boot 05 - 為 http json api 加入登入要求

科技新知
MacauYeah・2024-07-02

本節,我們將為之前的http服務,加入認證機制,只有在資料庫現存的用戶可以登入及訪問我們的json api。 下戴模版 慣例,我們用Spring Initializr (Maven) 下載模版,Dependency主要選擇 Spring Web Spring Boot DevTools Spring Security Controller 跟上節一樣,我們起一個Controller,為簡化測試,我們只做http GET api。 由於本blog對於Source Code的顯示不太友好,有需要看source code的,請到Github查看 //src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/controller/HomeController.java import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api") public class HomeController { @GetMapping("/someRecord/{uuid}") public Map readSomeRecord(@PathVariable String uuid) { return Map.of("ret", "your uuid:" + uuid); } } 準備我們的test case,但這次我們預期它應該要出現登入失敗的結果。 //src/test/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/controller/HomeControllerTest.java @SpringBootTest @AutoConfigureMockMvc public class HomeControllerTest { @Autowired private MockMvc mockMvc; @Test void testNoLogin() throws Exception { RequestBuilder requestBuilder = MockMvcRequestBuilders.get("/api/someRecord/1234") .contentType(MediaType.APPLICATION_JSON); this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.status().is4xxClientError()) .andExpect(MockMvcResultMatchers.jsonPath("$.ret").doesNotExist()) .andDo(MockMvcResultHandlers.print()); } } 在我們執行上述的測試,test case 成功過了。我們的基本設定跟上一節其實沒有多大改動,為何現在http api會回傳狀態 401? 那是因為我們在依賴中加了,Spring Security,它配合了Spring Web,就會自動為所有api加入權限檢測。我們的測試中,沒有任何用戶登入,當然會出現 http 401。為了讓我們可以好好管理誰可以使用api,我們就來設定一定Security。 我們加一個WebSecurityConfig.java,暫時指定所有的訪問路徑都必需有USER權限,並且用 http basic的方式登入。 //src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/config/WebSecurityConfig.java import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.Customizer; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; @Configuration @EnableWebSecurity public class WebSecurityConfig { @Bean SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http.authorizeHttpRequests(authorizeHttpRequests -> { authorizeHttpRequests.requestMatchers("/**").hasRole("USER"); // 所有的訪問路徑都必需有USER權限 }); http.httpBasic(Customizer.withDefaults()); // 使用http basic作為登入認證的方式 return http.build(); } } 上述例子,只是擋了沒有權限的人,我們還需要讓有登入身份的用戶可以成得取限User權限。 我們繼續修改,WebSecurityConfig,加入只在記憶體有效的InMemoryUser 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.provisioning.InMemoryUserDetailsManager; public class WebSecurityConfig { //.. @Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); // 我們的密碼不應該明文儲,比較保險,我們使用BCrypt演算法,為密碼做單向加密。 } @Bean public UserDetailsService userDetailsService() { UserDetails user = User.withUsername("admin") .password(passwordEncoder().encode("pass")) .roles("USER").build(); // 我們在記憶中體,加入一個測試用的User,它的名字為admin,密碼為pass,權限為User return new InMemoryUserDetailsManager(user); } 然後加入新的測試,直接模擬Role。結果是通過的。 //src/test/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/controller/HomeControllerTest.java @Test void testLoginWithRoles() throws Exception { RequestBuilder requestBuilder = MockMvcRequestBuilders.get("/api/someRecord/1234") .contentType(MediaType.APPLICATION_JSON).with( SecurityMockMvcRequestPostProcessors.user("someone") .roles("USER", "ADMIN")); // 沒有使用密碼,只使用Role this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.status().is2xxSuccessful()) .andExpect(MockMvcResultMatchers.jsonPath("$.ret").value("your uuid:1234")) .andDo(MockMvcResultHandlers.print()); } 再來一個測試,改用密碼登入,分別輸入錯的和正確的密碼。 @Test void testLoginWithWrongPasswordAndNoRole() throws Exception { RequestBuilder requestBuilder = MockMvcRequestBuilders.get("/api/someRecord/1234") .header("Authorization", "Basic randompass") // 輸入錯的密碼,應該回傳http 401 Unauthorized .contentType(MediaType.APPLICATION_JSON); this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.status().is4xxClientError()) .andDo(MockMvcResultHandlers.print()); } @Test void testLoginWithPassword() throws Exception { RequestBuilder requestBuilder = MockMvcRequestBuilders.get("/api/someRecord/1234") .header("Authorization", "Basic YWRtaW46cGFzcw==") // http basic 就是把 admin:pass 轉成base64 .contentType(MediaType.APPLICATION_JSON); this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.status().is2xxSuccessful()) .andExpect(MockMvcResultMatchers.jsonPath("$.ret").value("your uuid:1234")) .andDo(MockMvcResultHandlers.print()); } 最後,當然是正確的密碼才能通過。若果大家還是半信半疑,我們可以跑起真的正服務(IDE RUN或mvn spring-boot:run),然後用curl去試。 curl http://localhost:8080/api/someRecord/1234 // failed with 401 curl -u "admin:pass" http://localhost:8080/api/someRecord/1234 // successed 使用SQL Database讀取用戶登入資訊 一般而言,我們不可能把所有用戶登資訊打在InMemoryUser中,通常背後有一個資料庫儲存所有的用戶資訊,我們在登入時,讀取它來做對比檢證。 為此,我們在maven中,加入 Spring Data JPA h2 database (或任何你的資料庫,如mysql 、 sql server) 最後一步,我們把InMemoryUser去掉,改為從資料庫讀取。因為原始碼太多,就不全部貼上。最主要的是WebSecurityConfig.java要關掉之前的UserDetailsService,改為提供一個UserServiceImpl類,它會實現UserDetailsService的功能。 @Configuration @EnableWebSecurity public class WebSecurityConfig { // 把原來的Bean先變成註解,其他不變 // @Bean // public UserDetailsService userDetailsService() { // UserDetails user = User.withUsername("admin") // .password(passwordEncoder().encode("pass")) // .roles("USER").build(); // return new InMemoryUserDetailsManager(user); // } } // spring-boot-tutorial/spring-boot-web-api-data/src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/config/UserServiceImpl.java // other import import org.springframework.security.core.authority.SimpleGrantedAuthority; 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; @Service public class UserServiceImpl implements UserDetailsService { @Autowired PasswordEncoder passwordEncoder; @Autowired UserRepo userRepo; @Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { // 因為我們資料庫沒有資料,為了方便測試密碼的加密,我們在java code上直接插入一筆資料。 UserEntity defaultUser = new UserEntity(); defaultUser.setUsername("admin"); defaultUser.setPassword(passwordEncoder.encode("pass")); defaultUser.setRole("USER"); defaultUser.setUuid(UUID.randomUUID().toString()); userRepo.save(defaultUser); // 上述為測試用插入資料,不應該出現在正式使用環境中。 UserEntity user = userRepo.findOneByUsername(username) .orElseThrow(() -> new UsernameNotFoundException(username + " not found")); // 找找資料庫有沒有正在登入的該名使用者username List authorities = List.of(new SimpleGrantedAuthority("ROLE_" + user.getRole())); LOG.debug("got user uuid:{}, username:{}, role:{} from database", user.getUuid(), username, user.getRole()); // 如果前面的 findOneByUsername 有結果回傳,我們就給它一個ROLE_XXX的權限。 return new User(username, user.getPassword(), authorities); // 這裏從沒有檢查過密碼是否有匹配,全部交給Spring Security去做 } } //spring-boot-tutorial/spring-boot-web-api-data/src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/entity/UserEntity.java // spring-boot-tutorial/spring-boot-web-api-data/src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapidata/repo/UserRepo.java 上述段落中,筆者省略了UserEntity和UserRepo,它們只是一般的spring-data-jpa概念,有需要可以經文末的連結查看完全原始碼。最需要注意的,是UserEntity的password欄位,在資料庫中是以加密的方式儲存。我們在配匹登入者與資料庫記錄時,也沒有自行檢驗密碼的需要。我們只是在加密過的密碼回傳給Spring Security,Spring框架會自行把登入者輸入的密碼與加密了的密碼作比較。

珠海半小時車程一家大小可以去邊玩?

小城角落
MacauYeah・2024-06-28

珠海半小時車程一家大小可以去邊玩? 緊係要試上年新開今年初營業的珠海毛林金灣大酒店!!! 筆者聞說友人極推位於大灣區半小時車程新開的大酒店,內有中小童足夠喪玩的兒童遊樂城及冰雪運動城,酒店對面就是金灣華發商者,所以筆者當然要找個周末一家人上去放鬆一下。 國內酒店很方便,可以網購或找澳門旅行社訂都十分優惠,筆者比價後選擇了向本澳某大旅行社代訂兩天一夜套票,價格1,000澳門元,不過筆者揀咗車車主題房所以要再加多500澳門元。 雙人套票:包括早餐、兒童遊樂城、冰雪運動城、泳池及健身。 筆者訂購的是周五連周六(公眾假期)的兩天一夜套票,下午才可check in 酒店,但可於11:00後便可入場玩。筆者只有澳腳北上,所以過關後就直接約順風車,約40分鐘直達珠海毛林金灣大酒店。一到酒店,望落豪華的大堂大到呢…..應該有大半個足球場咁大 由於筆者的小朋友還嫰,當然係先去兒童遊樂城探個究竟先啦,一入到場,職員會俾廿個遊戲幣俾客人,但原來幣仲可以用黎夾公仔!!!正呀! 而場內所有遊玩設施都係免費任玩!!即刻沖入去睇吓: 場內樓高兩層: 下層有適合細B玩的大型波波池、迷你飄流、各式電動車、撈魚同積木等等;旁邊仲有岩大人玩的VR 遊戲!而另一邊仲有好多適合中童的大運動攀爬設施! 上層有其他電動遊戲、電動車、迷你war game場、當然唔少得各式玩具同零食夾夾機同小食區! 小朋友真係玩到樂而忘返,到咗晚飯時候當然要同佢講明天仲可以繼續玩先肯乖乖離開。 返到酒店房,唔洗多講一睇間房,嫰B十分喜歡嘩了幾聲,房間清潔,設備齊全仲備有兒童清洗用品,場內仲設有小帳幕同窗外望到開洋的美景。 房間隔音十分好,大家安睡一夜後,翌日先去嘆個自助早餐先! 同澳門五星級酒店有得揮喎,食物多,干淨服務不錯! 食飽轉場去冰雪運動城…… 場內有夠哂玩的仿雪滑梯 雖然哩兩日都十分大雨,幸好哩間酒店內有齊所有娛樂設施,大家都玩得十分滿足,總結哩個行程,性價比高! 溫馨提示:筆者首日同翌日入場的感受有好大差別,首日周五場內冇乜人,干淨安全不用排隊,但翌日是公眾假期,人山人海呀!!!所以雖是新酒店,但係內地玩都係要揀D冇咁多人的時間去比較輕鬆。 最後補充吓套票包咩,套票錢已包括酒店內所有設施,大家可盡情暢玩,但值得注意的是像我們一家三口,即多了一個人需要加購早餐及各場所入場門票。加購規則如下: 早餐:入住客人現場加訂早餐,獲門市價的8折(135人民幣/位(大小同價);身高1.2米以下小童免費,每一位成人限帶一名免費小童; 冰雪運動城:199人民幣/位大人,159人民幣/位小童,大人及小童必需穿帶指定裝備入場,裝備免費提供,但需付押金,離場後退回; 兒童遊樂城:79人民幣/位大人,99人民幣/位兒童; 備註:未滿18歲為兒童,18歲以上為成人,1歲以下免費入園,12歲以下兒童必須由一名成人陪同; 套票內包含的是2位成人門票,如入住時2大1小,小童需要現場加購小童價格的門票。 慳錢TIPS: 筆者獲酒店櫃檯職員告知雙人套票包的入場之手帶其實冇分大人定小童,持手帶便可入場,因此筆者帶同年僅兩岁的幼兒入場時,只加購了一張成人陪同票(成人票比兒童票便宜哦)

《魔物獵人世界》《魔物獵人崛起》通用心得

手機‧電玩
MacauYeah・2024-06-25

好久沒有寫Game心得分享,那是因為筆者也真的很久沒有開新坑。最近因為《魔物獵人》有新作預告,大家又好好地重新把《魔物獵人世界》拿出來練練手。筆者也順便把過去的買了沒有怎玩的《冰原》DLC拿出來,好好地玩一遍,總算完了一個心願。 因為玩了兩款近作,對於魔物獵人系統多少有一點入門心得,就來梳理一下,方便新朋友入坑時不再碰壁。 防具 隨著主線推進,不單武器可以強化,防具也可以繼續強化。強化等級因為階段推進而有突破。筆者以前就是不知道這件事,前期以為防具早已升滿,但後來一直貓車,才知道防具防禦力太低,需要經過重複強化提高防禦力。 防禦、體力增幅技能 防禦力、體力最大值兩者當然是越高越好。但在推進度前期,什至後期因為需要額外技能,防禦、體力不一定全滿。有必要時防禦增幅時選一半,體力增幅點滿比較好。因為後期挨怪物一套連招,即使防禦多高,也不能不回血。而體力增幅通常較易點滿,避免因為異常狀態影響而被連招到死,可以增加容錯率。而且後期回血道具一般直接使用秘藥,一次過回滿血條。所以筆者認為體力增幅比防禦增幅更有效。 防禦力疊加 若果你像筆者一樣菜,後期必需要使用各種方式疊加防禦力。主要方式有三個。食貓飯、道具持有、道具使用。貓飯在《魔物獵人世界》和《魔物獵人崛起》,都有機率成份,不過好在後期,總有票卷可以提升機率,筆者都偏向把投資在防禦力上。道具持有,主要在XX之爪和XX護符之上,帶著出戰就好,兩者最多各帶一份,但可以疊加。道具使用,就是硬化藥、硬化粉塵、忍耐種子。三種可以同時使用,可疊加,但硬化粉塵、忍耐種子有時效。 精靈加護 有一定機率減少傷害,但筆者後期不夠技能欄位,沒有去配。它也是增加容錯的機率,但防禦、體力、精靈加護全要的話,攻擊技能就更少了。所以筆者放棄它。 龍車 中後期,魔物都會四處跑,發怒時更是撞來撞去,總之就是讓你打空氣。筆者初時也不知道怎樣對策,總是跟著魔物屁股走。但其實這樣更費時,其實你可以原地等待,有空就調合或為武器上Buff,反正它很快就會回頭。想更有效的提升DPS,應該花時間去量度回來時的落點。魔物從遠處過來,但其實中途很少變向,比較有條件預判和輸出。若為團戰,因為有隊友分散仇恨,才需要主動追上魔物。 打點 初接觸這系列時,筆者就不斷看到【肉質】這一詞,但其實玩到現在,筆者都不太掌握。但通常都是集中打魔物的頭就了事。當打頭都出現彈刀時,再攻擊其他地方。有條件有心情,可以逐隻魔物研究,長期打到有效位置,傷害差很多,才能會易出現魔物倒地的狀態。 配裝 別人的配裝,其實自己並不一定能用,特別是那些TA影片(Time Attack)。MH系統的技能取得,都很有運氣成份,所以想要的技能不一定馬上能配到,大家主要去找自己武器的核心技能就OK。有些武器可能有多個流派,而且隨著時間累積,素材的隨機出現,我們有必要定期整理裝備組合。不同攻略網站,都會分享畢業裝,不過筆者到現在,都未去到這個攻守兼備的狀態。還是忘提畢業裝吧,後期的強怪,還是要針對性地重點挑整。 救援、團戰 有時卡關,有條件就叫救援吧,不必刻意自己打。因為進度限制,主線沒有推進的話,強化功能不開放,死磨也不一定有裝備提升。來救援的人一般是已推完主線,回來刷素材的,他們有較高的防禦去吸收傷害。他們不一定比你強,但貓的機率就比較低。但也不排除有時人沒打完主線就來抱大腿,結果搭沉船一起貓車。所以一定一定要準備【生命粉塵】,有必要時,就為殘血的同伴回血。那怕團友很強,也有機會出現異常狀態疊加的情況,為他回個血,他能更加集中輸出。 主機版都要買額外的會員制,才能聯機求助。PC版就沒有這個限制,接通網路就可以招外援。筆者推薦PC版,因為會員制的其他贈品都很雞肋,還不如PC版來得清靜。 以上,就是筆者玩完《魔物獵人世界》和《魔物獵人掘起》兩作的心得,雖然筆者還是很菜,但至少後期也玩得下去。希望以上各點可以為沒通關的朋友帶來實際的幫助。

github flow - github 開發流程

科技新知
MacauYeah・2024-06-20

那些年那個很穩定卻又不受歡迎的 git flow 開發流程 多年前,朋友就向筆者介紹git的團隊整操作流程。筆者深思過後,的確實用,那些年的git-flow,很美滿,由開發、測試,到發佈、修補漏動(backport),都有清楚明確的指引。 原作者連結:git-flow 大家如果沒有更複雜的需求,真的可以照搬,筆者也很推這一個模型。 但在長期推廣下,筆者發現大部份人其實都不熟git的基本操作,什至連git graph也不看,現在看git flow,就更不可能接受。那怕是有常用git的個人團隊,也是不怎使用分支模型。 前一兩年,筆者也不懂,筆者也努力地簡化git flow。例如把master和develop合而為一,但最後也是少有人可以接受,很多人還是卡在分支那邊,對checkout、merge還是很陌生。在跟更多不同人的協作過後,筆者總於意會到一件事。其實大部份人,只想知道最後、最新的狀態,只會更新 master / main ,也因為個人開發,所以連衝突也不會有,更不需要使用merge。那怕是少型團隊,頂多也是維護main的衝突,間中用用merge,而checkout還是用不著。 其實這個情況,並不限於小型團隊。因為 web app 和 DevOps 的流行,所以越來越少機會要維護多個舊的穩定版本。大家都專心於最後一個開發及發佈版本就完事,用戶的某個版本有問題?更新到最新版本吧。(註:越底層的應用開發模式,因為相容性問題,不可能只保留一個穩定版本。) 那麼我們就大力簡化吧 - github flow 開發流程 既然大部份情況,大家都只在乎 main / master / 預設分支,那我們也沒有必要跟著複雜的 git flow 走。但在 DevOps 的角度下,為保證 main / master 穩定性,大家還是至少要遵守branching 、pull (merge) request 、code review 、auto test 原則 。 github就最簡單的branching 、pull request 、code review 提出了它們的 github flow。 簡而言之,就是每個人在開發時,都先從 main 起一個新分支,不斷更新。待合適的時候,就透過 pull requst,向原項目負責人提出申請,只要項目負責人點頭,就可以把改動傳入 main 中。又因為Github 原本的定位在於個人與個人之間的協作,初時已經需要通過fork建立獨立的倉庫,那怕你不愛分支也必需分支。所以 pull request,code review 的作用更明顯,後逐的協作更理所當然。 但若果回到公司團隊協,Github flow 就應該像筆者之前提出協作方案,各自起分支,最後由某個人守門,把所有結果放到 main 中。(前文連結)

Coding Anywhere 工作方案

科技新知
MacauYeah・2024-06-13

最近筆者一直在準備軟件開發的教材,因為各種原因,例如:新舊硬件交替,沒有固定的電腦等等,讓寫稿和設計教程的進行得很慢。但其實這種情況並不旱見,即便是真正的開發團隊,也會時時刻刻面對各種新舊設備的更換。在不久的未來,這種更替速度可能更頻繁,工作模式也很可能趨向這樣,為了打造更靈活的工作方案,適筆者一直為自己的coding anywhere情境物色合適的工具。 基本假設 在分享之前,有些前題條件必需要滿足,coding anywhere的基本條件是我們可以把一些厚重的資源變成cloud或遠端工作,如果你是開發主機遊戲,你的測試必需要在PS5上跑,那就沒有條件帶著裝備走。即使你可以設定遠端連線,但你人在外,其實沒法在PS5上做互動。真正有條件實行的工作,必需要可以在外由開發至測試都行得動。 在這個前題下,筆者就開始分享一些自己嘗試過不同組合。 不可或缺的東西 - 滑鼠、網絡 這件事,看似不重要,但筆者一直沒法找到完美的解決方案。 無線滑鼠是標準配置,筆者曾經想去掉滑鼠,但不太可行。這個大家還是選一個不太大,而且可以穩定在不同機器切換的滑鼠吧。至於鍵盤,視乎你的主機有沒有實體鍵盤,如果最後選擇平板或掌機的話,還是需要帶鍵盤外出,亦即是不論你選擇何種方案,鍵盤的重量也是不會消失的。 另一個就是網絡流量問題。我們處身的環境,並不一定有免費網絡。有時為了安全性,我們不想配對公用Wifi。那怕不考慮安全問題,公用Wifi都很常出現因為人流太多而被踢的情況,所以一般都考慮直接使用手機的4G/5G網絡。而為了節省流量,一般控制好大檔案/大更新的下載時機,都是可以達到的。 不同的工作模式,不同的選擇 上述第一個問題在筆者看來,都屬於沒有選擇,但下面的選擇,可以基於價錢、功能、需要而搭配。另外,我們還要假設我們有足夠的Remote資源可以用。但如果大家的開發,必需要帶著硬件資源,就不太可能實現coding anywhere。 一台入門級的Notebook 如果我們大部份工作,都可以經Cloud Service解決的話,其實我們不必投資太多在主機之上。Notebook帶著四處跑,壞的可能性也多,入門級的Notebook就算壞了也沒有那麼心痛。 全Cloud Service還有另外一個好處是不需要擔心備份問題,壞了Notebook就狠心換機。而且Cloud Service的好處是需要更新client software的網絡流量消費不高,不過想真省錢的話,就需要好好控制cloud service。 例子1,如果大家熟識或願意使用github codespace或gitpod等全cloud IDE,Notebook只需要安全Browser就夠。所有IDE, VM都由github或gitpod提供,它們各自有各自的免費用量,也就是說,當大家真的不夠用又不想付費,可以兩著切換用。真的不夠用,就時租codespace 2G 每小時$0.18USD,約為每小時1.44MOP。 例子2,如果大家有自己Cloud VM,可以用VS Code + SSH,除SSH的extension外,其他安裝及運行在VM中,對Notebook client的要求不高。Cloud VM品牌可以使用Digital Ocean、Linode等,2G機器價錢更低,每小時0.018USD左右,不過就要自己初始化各種工具。 一台高階的Notebook 這個方案可能就不需要再多解釋了,那就是你把家裏的核心電腦帶著到處走,一切都自給自足。在外的不可控因素可能就只有電量控制。另外一方面,長期的備份和維修成本也是需要考慮的。 輕便裝:一台中階大平板 跟上面的遊戲用PC掌機類似,不過螢幕更大,但缺點是配上鍵盤後,價錢比得上一台中階電腦,出門的重量也比得上電腦。在軟件上,你還必需要選擇Cloud VM,Local IDE也不一定有。所以在成本上來講,沒有很太優勢。大平板可能只對那些有專門APP需求的用戶有意義。 究極輕便裝,一台7/10寸入門平板 大平板最大的問題是價錢,但如果換成小平板,一切就不錯了,壞了也沒有那麼心痛。源用所有純Cloud解決方案。出門的負重最低,電量也最有保證。這是筆者最推薦的方案。 低成本高階機:遊戲用PC掌機 對,你沒有看錯,筆者指的是主打遊戲的PC掌機,也是筆者現時自己的最佳方案。假如你在工作室、家、公眾環境來回切換,很擔心傷到Notebook的話,那麼買台低成本的PC掌機絕對是可以接受。有些很重要的底層功能,需要多台Cloud VM,可能花費很高,所以還是需要經Local實現比較有性價比。 它最重主要的問題是螢幕小和沒有鍵盤,但這個程度,對比入門平板來講,其實都差不多。但它比平板有更強的CPU、RAM,作為移動核心電腦一定沒有錯。你還可以自由選擇Local VM、Cloud起VM。

何謂 Infrastructure as code - IaC

科技新知
MacauYeah・2024-06-07

在雲端服務出現後,好多新的名字,或許大家都聽過,筆者也稍為再簡介一下。 Software as a Service (Saas)。就像我們的Web App,不用下載體件,可以直接經雲進行業務操作。 Platform as a service (Paas)。這個概念可能最含糊,筆者理解就是,雲端供應商提供一些底層的軟件,供IT人使用。像是資料庫,Web Engine。 Infrastructure as a Service (Iaas)。這個更底層,雲端供應商給出CPU, IP, Memory, Storage等,頂多就再多個預安裝OS的選項。IT人自己去配搭使用。 多得這些彈性服務,雲端應用才真的跟過去租用實體伺服器有所差異。 但對於IT人來講,要使用這麼多不同的服務,實在也不簡單。對於IT消費方,用錢換來實體硬件的靈活性,但因為硬件沒有邊界之後,軟件的量就暴增。管理也不能說是很方便。 在Docker, Kubernetes等Container(容器)出現後,又為這些管理問題帶來另一種希望,就是Infrastructure as code - IaC。它的目標是,管理基礎設施,要像管理原始碼一樣,checkout 就可以回覆到指定狀態。 初聽之下,大家可能覺得好玄,但其實這個概念,在之前筆者的Docker 教學中,已經有出現過。Docker compose 、Docker stack 指令,它們都是基於yaml檔的IaC。 當筆者更新了yaml 檔,執行一次stack deploy ,docker 就會對比之前狀態,如果replica(分身)不夠多,就自動增加所欠數量,如果image 也更新了,就排隊輪流重起換image 。最重要的是,當我們checkout 舊的yaml 檔,回到過去某個狀況,只要還是執行同一句stack deploy ,系統就自然減少所需的replica數量,下戴過去的image。這就代表,我們對於container 構建而成的環境,都可以放入Git等版本控制中,整個管理模式,就像管理程式碼一樣(GitOps)。 對於更進階的Kubernetes更是如些,除了container外,多種不同的network,storage配置,都通過yaml檔進行控制。這樣,架構即使複雜,但只少可以測試、重現和管理。還有一個,它比Docker stack要強的是,它某程度上支緩刪除的概念。雖然不完全,但總比完全沒有方便。 這個IoC的概念,可能還未達到一定廣泛地應用的階段,但它的核心在於,基建項目有檢測試差異的功能,自動去因為這個差異去加或減資源。用Programmer的講法,就是系統有Diff的功能,自動多除少補。

開發者在Steamdeck上的另一個選擇: Gnome box

科技新知
MacauYeah・2024-05-28

前些日子,因為升級podman的關係,筆者對Steamdeck的限制就更為了解。因為Steamdeck是一個修改過的Arch linux,不單止代表是某些區塊是唯讀不可寫。更深一層的問題是,有些依賴包,不能簡單地通過安裝或自行編輯來解決。 例如早前podman 5.0.x需要的pasta依賴,雖然Arch linux官方有這個lib的發佈,但Steamdeck沒有選用,那些我們自己下載原始碼,你地會發現steamdeck的gcc或cc編譯指令還法完全執行,一來是編譯器指令沒有預設對,另一方面則是缺少了更多的c lib (.h) 依賴包。最後筆者只好選擇下載pasta官方預編譯的二進位程式。能用,但就總是多少有點不安心。因為pasta的預編譯只是針對x86_64的CPU,並沒有考慮link lib的問題,不過這次運氣還算可以,沒有無盡依賴的問題。 回來講Steamdeck的情況,之前筆者介紹brew,其實是macOS帶過來的,雖然他們對其他linux的支援很不錯,但多少都基於某些低層的依賴包可以隨時更新。而Steamdeck這個限制版,就沒有保證linux 依賴包的預安裝。(那怕是Ubuntu也是一樣,只是我們可以通過進一步的指令案裝就可以了。)所以在Steamdeck上,長遠還是要找一些官方維護的軟件比較安全。 Steamdeck上預設的是依賴安裝是【Flatpak】,雖然它不像yum, apt, dnf這些仔細可以安裝原始碼依賴,但它們可以安裝App,例如Firefox、Chrome、輸入法等。遺憾的是,Flatpak上沒有podman, docker,對於開發者來說就很不方便。 但最後,筆者終於在【Flatpak】上發現一套【BOX】VM解決方案。它的功能不算強大,但至少可以經ISO安裝自己想要的OS,也有快照功能(只限關機狀態下)。BOX官方亦表明,這套VM不是針對自動化或企業管理所做的,只有一些基本操作。 官方連結: https://apps.gnome.org/Boxes/ 官方原始碼: https://gitlab.gnome.org/GNOME/gnome-boxes Flathub載點: https://flathub.org/apps/org.gnome.Boxes 對於筆者來說,能裝到VM,代表就有更多的操作空間。如果大家不介意多了一些虛擬層,會太影響效能,其實很多操作可以在VM內使用。例如不需要再用podman,可以直接在VM中使用docker、安裝k8s等。對於效能問題,我們必需要在Steamdeck操作時,至少我們可以在VM中先安裝Arch linux,找回必要的依賴包,編譯我們想要的link lib,再抄回Steamdeck下執行。過程的確比較轉折,但若然Steamdeck這台機器只適合打機的話,就真的很可惜。

Spring Boot 04 - 進入http json api 世代

科技新知
MacauYeah・2024-05-23

本節,我們將會建立一個http服務,提供json api讓程式訪問。 下戴模版 我們跟上節一樣,使用Spring Initializr (Maven) 下載模版,但細節筆者就不再講啦。Dependency主要選擇 Spring Web Spring Boot DevTools 下載後,可以直接運行測試,可以用指令 mvn test 或經IDE運行。Spring會至少測試下能不能成功取用預設的8080端口。 Controller 我們若要實作 http json api,需要在 spring 中加入一個類,附註為 @RestController ,那方便起見,類名我們也命名為 XXXController 吧。作為示範,我們弄一個 HomeController.java ,裏面有最常見的 http GET, POST功能。 // src/main/java/io/github/macauyeah/springboot/tutorial/springbootwebapibasic/controller/HomeController.java import org.springframework.web.bind.annotation.RestController; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; // ... other import @RestController @RequestMapping("/api") public class HomeController { @GetMapping("/someRecord/{uuid}") public Map readSomeRecord(@PathVariable String uuid) { return Map.of("ret", "your uuid:" + uuid); } @PostMapping("/someRecord") public Map createSomeRecord(@RequestBody Map requestBody) { HashMap ret = new HashMap(requestBody); ret.put("ret", "got your request"); return ret; } } HomeController裏,完整的URL 其實為: GET http://localhost:8080/api/someRecord/{uuid} POST http://localhost:8080/api/someRecord URL中的api之後的路徑,都是定義在 HomeController 中,而前半的8080及context path,是使用預設值。在正式環境下,可能隨時會被重新定義。但我們做本地測試,只需要驗證預設值就可以了。 我們真的運行起程式mvn clean compile spring-boot:run,再使用最簡測試工具進行測試。Windows的朋友,可以選擇Postman作為測試,它有圖形介面。而linux的朋友,請用curl,預設安裝都會有。下列為方便表示測試參數,筆者選用curl。 測試GET,其中1234會自動對應到spring裏的uuid。 curl http://localhost:8080/api/someRecord/1234 # return {"ret":"your uuid:1234"} 測試 POST,其中的 -d 參數,會對應 spring裏的 @RequestBody, -H 參數則是設定 http header 的意思,我們就使用約定俗成的 json 作為 header 。 curl -X POST http://localhost:8080/api/someRecord -H "Content-Type: application/json" -d '{"requst":"did you get it?"}' # return {"requst":"did you get it?","ret":"got your request"} 上面的兩個操作,都回傳了我們輸入的資訊,這代表了我們成功用spring架起了http json api,而且正常讀入資訊。 Test Case 雖然我們可以正常地架起 api,但每次開發都要 postman / curl這種工具額外試一次,其實也有一些成本。而且 api 數量變大,或經多次修改後,就重複人手執行,就變得相當討厭。 面對這個問題,筆者會建議寫測試用例,即是Test Case,而且用Spring內置的@SpringBootTest來寫。 產生一個空的Test類,vscode中,最簡單可以Source Action => Generate Test,然後加入這次要測試的參數。 // src/test/java/io/github/macauyeah/springboot/tutorial/springbootwebapibasic/controller/HomeControllerTest.java import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.http.MediaType; import org.springframework.test.web.servlet.MockMvc; import org.springframework.test.web.servlet.RequestBuilder; import org.springframework.test.web.servlet.request.MockMvcRequestBuilders; import org.springframework.test.web.servlet.result.MockMvcResultHandlers; import org.springframework.test.web.servlet.result.MockMvcResultMatchers; @SpringBootTest @AutoConfigureMockMvc public class HomeControllerTest { @Autowired private MockMvc mockMvc; @Test void testGetSomeRecord() throws Exception { RequestBuilder requestBuilder = MockMvcRequestBuilders.get("/api/someRecord/1234") .contentType(MediaType.APPLICATION_JSON); this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.jsonPath("$.ret").value("your uuid:1234")) .andDo(MockMvcResultHandlers.print()); } @Test void testPostSomeRecord() throws Exception { String request = """ {"requst":"did you get it?"} """; RequestBuilder requestBuilder = MockMvcRequestBuilders.post("/api/someRecord") .contentType(MediaType.APPLICATION_JSON) .content(request); this.mockMvc.perform(requestBuilder) .andExpect(MockMvcResultMatchers.jsonPath("$.requst").value("did you get it?")) .andExpect(MockMvcResultMatchers.jsonPath("$.ret").value("got your request")) .andDo(MockMvcResultHandlers.print()); } } 最後就是執行 mvn test 或經IDE運行,應該都會得到所有測試都通過的結果。 mvn test # other test result ... [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.368 s -- in io.github.macauyeah.springboot.tutorial.springbootwebapibasic.controller.HomeControllerTest # other test result ... 上面的程式碼很多,我們逐一來。 @SpringBootTest 寫在類的外面,代表執行這個測試類時,需要運行起整個Spring程序,當然也包括http的部份。 @AutoConfigureMockMvc 寫在類的外面,代表執行這個測試類時,可以模擬一些發向自己的 http 請求。 @Autowired private MockMvc mockMvc 寫在類的裏面,因為之前有定義了可以模擬 http 的請求,Spring在運行時為大家提供了那個所謂的模擬http client的實例。 MockMvcRequestBuilders,則是建造要測試的URL及Header參數。 MockMvcResultMatchers,則是檢查回傳的結果是否如遇期的一樣。 為何這個http client叫模擬 - Mock ? 因為在測試用例中,可能連Controller 內部依賴組件也需要進一步模擬,這樣才能把測試目標集中在Controller裏,這也是單元測試的原意。只是本次的例子看不出模擬與否的差別。 MockMvcResultMatchers.jsonPath(),這是用來檢測json的結構是否跟預期一樣。有些網路上的其他例子會簡寫成 jsonPath() ,但因為vscode IDE的自動import功能比較差,筆者還是保留傳統的寫法。 如果大家覺得@SpringBootTest很難,想折衷地把其他測試方法,那麼把 postman / curl好好管理起來,每次修改完程式,都完整地執行一次 postman / curl ,也可以達到測試的效果。只不過大家還是要好好學會整合 postman / curl,知道如何檢測json結構,什麼時候有錯,什麼時候叫測試通過,所以也要花一樣功夫來實現。 最後,大家千萬不要因為測試難寫而逃課,因為寫測試絕對地可以減輕日後重執行的工作量。除非你的程式碼即用即棄,否則都建議寫測試。(測試跟寫文檔不一樣,有了測試也不能沒有文檔。好消息的是,文檔現在越來越多自動生成的工具,我們日後再找機會介紹。) Source Code spring boot web api basic

Ubuntu 24.04 試用報告-更新

科技新知
MacauYeah・2024-05-21

上期為大家介紹了一些ubuntu docker, multipass的一些改動。本期再繼續介紹一些其他的更新。 apt中的source.list 的位置更新了,格式也更新了,從/etc/apt/sources.list在指向了/etc/apt/sources.list.d/ubuntu.sources,格式變得更親民,就像如下所示 Types: deb URIs: http://mo.archive.ubuntu.com/ubuntu/ Suites: noble noble-updates noble-backports Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg Types: deb URIs: http://security.ubuntu.com/ubuntu/ Suites: noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg 承上更新,雖然格式好看了,noble-security的部份卻故意折開了。而且在live-cd初次安裝時,大家若要改mirror(鏡像站點),只能修改noble noble-updates noble-backports的位置,noble-security還是會指定在官方的位置。筆者猜測它的用意是針對安全性更新,大家應該要直接訪問官方網站,不要等mirror慢慢更新。此一更新,不單影響ubuntu 24.04,連ubuntu 22.04也受一併折開了,只是22.04還是使用舊版。如果有需要變回統一的方向,減少日後自動化的修改,可以像以下修改 ubuntu 24.04的修改 Types: deb URIs: http://mo.archive.ubuntu.com/ubuntu/ Suites: noble noble-updates noble-backports noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg ubuntu 22.04.04的修改,刪除/etc/apt/sources.list,新增/etc/apt/sources.list.d/ubuntu.sources (對齊ubuntu24的位置) Types: deb URIs: http://mo.archive.ubuntu.com/ubuntu/ Suites: jammy jammy-updates jammy -backports jammy-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg