song of the day

SpringBoot 支援了 RESTful web 服務。在第十天的文章中要來探討如何利用 @RestController 和 @RequestMapping 註解來快速創建 REST API。

1. 什麼是 REST?

REST，即 Representational State Transfer，是一種軟體架構風格(而非標準)，特別適用於分散式系統如 Web 應用。它使用標準的 HTTP 方法來進行互動，如 GET、POST、PUT、DELETE 等。

2. @RestController

在 SpringBoot 中，為了將一個 class 定義為 REST API 的控制器，我們使用 @RestController 註解來告訴 Spring 這個 class 的目的是處理 HTTP 請求。與 @Controller 不同，@RestController 表示每個方法返回的都是直接的 ResponseEntity。

例如：

@RestController
public class MeowController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

當你存取了 /hello 路徑，會收到 "Hello, World!" 這樣的 response。

3. @RequestMapping

使用 @RequestMapping，我們可以定義具體的 HTTP method 和 URI 模式來進行 mapping。

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // ... 查詢並回傳 user
    }

    @PostMapping("/")
    public User createUser(@RequestBody User newUser) {
        // ... 創建並回傳新 user
    }
}

在上面的例子中，所有方法都會 mapping 到 /api/users。具體的 HTTP method 和 URI 取決於每個方法上的 annotation。

4. 結合 @RestController 和 @RequestMapping

透過結合使用 @RestController 和 @RequestMapping，可以創建靈活的 RESTful API。例如，以下是一個完整的 CRUD controller：

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/")
    public List<Product> getAllProducts() {
        // ... return 所有產品
    }

    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        // ... return 指定的產品
    }

    @PostMapping("/")
    public Product createProduct(@RequestBody Product product) {
        // ... 創建並 return 新產品
    }

    @PutMapping("/{id}")
    public Product updateProduct(@PathVariable Long id, @RequestBody Product updatedProduct) {
        // ... 更新並 return 產品
    }

    @DeleteMapping("/{id}")
    public void deleteProduct(@PathVariable Long id) {
        // ... 刪除產品
    }
}

5. @RequestMapping 參數

在使用 @RequestMapping 時，我們可以更精確地控制 mapping 行為。以下是一些常用參數：

• consumes：這個參數可以指定接受的 request 內容類型。例如，只想接受 JSON 格式的資料就可以使用 @RequestMapping(value="/users", consumes="application/json")。
• produces：與 consumes 相反，這是指定 response 的內容類型。例如只想回傳 XML 格式之資料可以使用 @RequestMapping(value="/users", produces="application/xml")。

6. HTTP status code 的重要性

當我們與客戶端互動時，應該提供合適的 HTTP 狀態碼。這不僅有助於客戶端判斷打這隻 api 的結果，還有助於錯誤追踪和 debug。Spring MVC 提供了 ResponseEntity 用來回傳特定的 status 和 body。

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    User createdUser = userService.save(user);
    return new ResponseEntity<>(createdUser, HttpStatus.CREATED);
}

7. 安全性與 REST API

開發 REST API 時必須重視安全性。使用 Spring Security，我們可以控制哪些角色可以存去特定的 endpoint、誰可以查看、修改或刪除資料。它還支援各種身份驗證方法，如基本身份驗證、OAuth2等。

http
    .authorizeRequests()
    .antMatchers("/admin/**").hasRole("ADMIN")
    .antMatchers("/users/**").hasAnyRole("ADMIN", "USER")
    .and()
    .httpBasic();

8. 跨來源資源共用 (CORS) 在 SpringBoot 中的配置

當前端和後端部署在不同的域名上時，瀏覽器的同源政策 Same-origin policy 會阻止跨域請求。但可以在 Spring 更改配置 CORS：

@Configuration
public class MyConfig {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurerAdapter() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**")
                        .allowedOrigins("<https://yourfrontend.com>")
                        .allowedMethods("GET", "POST", "PUT", "DELETE");
            }
        };
    }
}

以上是使用 @RestController 和 @RequestMapping 來定義 RESTful API 相關的內容介紹，今天就先這樣拉，明天見～