網站技術 Backend 前後端如何和平相處 2022ironman

Web API 實作解析 從把妹角度理解前後端如何和平相處

me
林彥成
2022-09-17 | 3 min.
文章目錄
  1. 1. API 規格文件撰寫
  2. 2. API 系統實作
    1. 2.1. JavaScript API X Expressjs
    2. 2.2. Python API X FastAPI
    3. 2.3. Java API X Springboot

小編在另外兩篇文章分別介紹了什麼是 API和 API 系統設計方法，談了許多 API 概念上的東西。

這篇文章會從實作的角度用 JavaScript、Java、Python 來實作後端的 Web API。

實作就是最好的學習，這就跟讀了很多把妹相關的書籍，還不如註冊個交友軟體天天練習跟女生聊天一樣，小編在年初也是因為受到直屬學弟們的鼓勵就真的註冊了而且還天天晚上都在熬夜聊天。

Web API 在實作上主要是兩個步驟

  1. API 規格文件撰寫
  2. API 系統實作

API 規格文件撰寫

這裡先手動進行 Swagger 的 YAML 撰寫，撰寫語法不困難。

底下列出一個基本的範例，整份文件其實就圍繞著 API 的輸入及輸出兩大重點

  1. 輸出: 定義回傳資料格式
1
2
3
4
5
6
7
definitions:
  Book:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
  1. 輸入: 定義路徑與 HTTP 方法及輸入參數
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
paths:
  /api/v1/book/{bookId}:
    get:
      tags:
        - "Book"
      summary: "Find Book by ID"
      description: "For valid response try integer IDs with value >= 1"
      operationId: "getBookById"
      produces:
        - "application/json"
      parameters:
        - name: "bookId"
          in: "path"
          description: "ID of pet that needs to be fetched"
          required: true
          type: "integer"
          maximum: 10.0
          minimum: 1.0
          format: "int64"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Book"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Order not found"

各位大大可以自行複製完整的版本到線上的 Swagger Editor 看看結果。
Swagger Editor: https://editor.swagger.io/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
swagger: "2.0"
info:
  description: "API 文件"
  version: "1.0.0"
  title: "Swagger Book Store"
host: "swagger.io"
basePath: "/v1"

schemes:
  - "https"
  - "http"
paths:
  /api/v1/book/{bookId}:
    get:
      tags:
        - "Book"
      summary: "Find Book by ID"
      description: "For valid response try integer IDs with value >= 1"
      operationId: "getBookById"
      produces:
        - "application/json"
      parameters:
        - name: "bookId"
          in: "path"
          description: "ID of pet that needs to be fetched"
          required: true
          type: "integer"
          maximum: 10.0
          minimum: 1.0
          format: "int64"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Book"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Order not found"
definitions:
  Book:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"

一個較正式且完整的文件範例:

API 系統實作

後端的 API 其實不限制用什麼語言進行撰寫，各種語言撰寫上需要注意的觀念也大同小異，建議選擇熟悉的語言進行學習即可。

API 撰寫上有三個重點

  1. 路徑: 包含版本、符合 REST 的規範
  2. 輸入: 參數的各種類型
  3. 輸出: 回傳格式

每個語言會有各自特性還有需要注意的觀念，底下會就小編的理解跟大家分享和解釋。

JavaScript API X Expressjs

  1. 觀念:
    JavaScript 後端的實作語法概念跟前端其實並沒有太大的差異，觀念主要是單線程且 non-blocking 的設計，正常執行每一行程式時都不會卡住，所以大多都會搭配 Callback Function 進行處理。

  2. Swagger:
    可能因為不是強型別，所以需要手工撰寫 OpenAPI 格式的 yaml 才能夠支援 Swagger。

  3. 延伸閱讀:
    由於 Express 這類框架無法操作資料庫，所以將資料表示為 JavaScript 的 Object，再透過 ODM/ORM 工具去達到操作資料庫的目的，推薦透過 Mongoose 操作資料，只要三步驟就能打穿 MongoDB 到 API，ODM/ORM 通常能降低開發及維護成本，網站分成前跟後端而 Mongoose 也可以看成是 MongoDB 的前端介面。

範例程式碼:

1
2
3
4
5
6
7
8
9
10
const express = require("express");
const app = express();

app.get("/api/v1/book/:bookId", (req, res) => {
  res.json({ bookId: req.params.bookId });
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Python API X FastAPI

  1. 觀念:
    打字打最少也最方便的一個語言，FastAPI 提供了方便快速開發的環境，透過自動產生文件與支援型別確認減少錯誤，官方文件表示能夠減少大約 40% 的人為錯誤。

  2. Swagger:
    內建自動產生 openapi 的即時文件支援 Swagger、redoc，詳細說明可以參考這份文件: https://fastapi.tiangolo.com/#interactive-api-docs

  3. 延伸閱讀:
    Python FastAPI 快速入門，7 行程式完成 API 和線上互動文件。

範例程式碼:

1
2
3
4
5
6
7
8
from fastapi import FastAPI
app = FastAPI()

@app.get('/api/v1/book/{bookId}')
def get_book_by_id(bookId: int):
    return {
        'bookId': bookId
    }

Java API X Springboot

  1. 觀念:
    Java 後端的框架看來看去其實就是兩個觀念，Inversion of Control (IOC) 跟 Dependency Injection (DI)，控制反轉實作上會使用 @ 的方式來進行依賴注入。

  2. Swagger:
    支援 Swagger 文件自動產生: https://www.baeldung.com/spring-rest-openapi-documentation

  3. 延伸閱讀:
    Java Web API (RESTful API) 教學，三步驟打通關節開發 API 後端服務，主要會示範使用 Jersey 這套框架從 0 到 1 打造一個網站應用程式，並整理 Java Web Appication 相關資源如基礎建設、前端網頁、後端 Web API 及資料庫。

範例程式碼:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@SpringBootApplication
@RestController
public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }

  @GetMapping("/api/v1/book/{bookId}")
  public ResponseEntity<String> getBookById(@PathVariable String bookId) {
    return bookId.ok(bookId);
  }
}

喜歡這篇文章，請幫忙拍拍手喔 🤣

站內搜尋
其他相關文章
最新的文章