Co ban ve HTTP — phuong thuc, ma trang thai, tinh idempotent

1. HTTP nhu mot hop dong: request → response

Khi moi nghe den “HTTP”, nhieu nguoi thuong nghi: “thi no la ve website ma”. Va dung, website cung the. Nhung voi developer, HTTP truoc het la mot cach rat chat che de thoa thuan giua hai chuong trinh: mot ben gui request (client), ben kia tra loi (server). Thoa thuan nay duoc goi la hop dong, va no khong chi bao gom “URL nao can goi”, ma con co “method nao”, “ma nao la thanh cong/loi”, “dinh dang body nao”, “dau vao nao duoc xem la hop le”.

Trong Go, dieu nay dac biet thich: Go theo lich su la mot ngon ngu rat manh cho server va code mang. Ngay ca trong cac tai lieu ve su phat trien cua Go, nguoi ta cung nhan manh rang Go duoc thiet ke de viet server.

Mo hinh tinh than “phong bi”

Hay tuong tuong HTTP nhu buu dien.

• Thu = request.
• Phong bi = metadata (method, path, headers).
• Noi dung thu = body cua request (vi du JSON).
• Thu tra loi = response.
• Tem tren thu tra loi = status code (200, 404, 500...), thu gon va ro rang ve “dieu gi da xay ra”.

Nghe co ve hoi cu, nhung nhu mot mo hinh tinh than thi no hoat dong rat tot: server khong “doan theo cam tinh”, ma phan hoi mot cach hinh thuc.

So do request va response

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: HTTP Request (method + path + headers + body)
    S->>S: validate + compute
    S-->>C: HTTP Response (status + headers + body)

Y nghia quan trong nhat tu so do nay: dau ra luon co status code, con body cua response co the co hoac khong. Va client phai biet song dua tren status code, thay vi co gang “doc loi bang mat”.

Endpoint: method + path

De dung HTTP nhu mot thu “ma thuat”, hay dat ra mot thuat ngu nho: endpoint — day la “diem vao” cu the trong API. Va no gom hai phan: HTTP method (lam gi) va path (lam voi cai gi).

Vi du, “lay danh sach tasks” thuong co dang GET /api/v1/tasks.

Bay gio chung ta khong chay server va khong viet handler. Chung ta lam dieu ma cac ky su truong thanh lam o dau du an: chot hop dong. Va de lam dieu nay, co the viet vai struct trong Go — khong phai vi “can code”, ma de suy nghi ro hon.

Mini type de mo ta endpoint

package main

type Endpoint struct {
	Method string
	Path   string
}

var listTasks = Endpoint{Method: "GET", Path: "/api/v1/tasks"}
var createTask = Endpoint{Method: "POST", Path: "/api/v1/tasks"}

O day dieu quan trong khong phai la “dep code”, ma la ky luat tu duy: endpoint chinh la cap (method, path). Neu ban doi method, ban doi y nghia. Neu ban doi path, ban doi resource.

2. HTTP methods: y nghia cua hanh dong va loi hua voi client

Co the hieu methods nhu dong tu voi nhung quy tac rat chat che. Neu ban dung methods “tuy hung”, client se phai doan hanh vi, va API se giong nhu mot quest “doan nut bam”. Neu ban tuan thu semantics chuan, client (va cac lap trinh vien khac) hieu hanh vi ma khong can doc source cua server. Dieu nay tiet kiem gio, tiet kiem than kinh va ca so luong tin nhan “sao o day 200 ma lai la loi?”.

Duoi day la mot bang thuc te, thuong duoc ghi nho khi thiet ke API.

Bang semantics co ban cua methods

GET

POST

PUT

PATCH

DELETE

Mot vai ghi chu de no khong tro thanh ly thuyet kho hon.

GET gan nhu luon an toan theo nghia la khong nen doi trang thai tren server. Neu GET ma tu nhien tao task, tru tien va gui email cho me ban — thi do khong phai GET, do la kich ban phim kinh di.

POST thuong duoc dung de tao moi: “tao task”, “tao user”. Nhung doi khi POST la mot “lenh” khong khop voi kieu “thay the trang thai”. Vi du: “khoi dong lai viec tinh toan bao cao”. Trong domain tasks minh dang hoc, chung ta se co gang giu POST nhu “tao task”, vi cach nay de hieu hon.

PUT va PATCH: neu ban khong chac, dung voi vang ap dung chung. Nhung hieu y nghia la quan trong: PUT la “day la phien ban moi cua resource, toan bo”, con PATCH la “day la thay doi nho”.

DELETE — xoa. Va o day bat dau co tri hoc: neu resource da bi xoa roi thi sao? Thuong nguoi ta thoa thuan de lan goi lai DELETE khong lam hong he thong.

3. Status code: ngon ngu phan hoi cua server khong can doan qua chu

Neu method la “chung ta muon gi”, thi status code la “dieu gi da thanh cong”. Va do khong phai chi tiet phu: no la mot phan cua hop dong. Client viet logic dua vao code. Trong mot API tot, client khong can “doc mot dong error” de hieu ban muon noi gi. No thay 404 va hieu “khong tim thay”. No thay 400 va hieu “toi da gui sai gi do”.

O day co mot mo hinh tinh than rat tien: nhom code.

• 2xx — thanh cong,
• 4xx — van de o request (client co loi, hoac it nhat client co the sua),
• 5xx — van de o server (client khong co loi).

Ham nho “class cua code”

package main

func statusClass(code int) int {
	return code / 100
}

// 200 -> 2
// 404 -> 4
// 500 -> 5

Dung, day la toan hoc cap 1. Nhung no rat huu ich: thay statusClass == 4 — nghia la “loi request”. Thay statusClass == 5 — “co gi do bi hong o phia chung ta”.

Tap hop code toi thieu ma ban can hieu chac chan

Trong pham vi API tasks tuong lai, chung ta chi can mot “bo co ban 5” nho gon (va them mot):

200

201

204

400

404

500

Chi tiet quan trong ve 204: do khong phai la “200 nhung khong muon noi gi”. Day la tin hieu ro rang: “thanh cong, khong co body”. Neu ban tra ve 204 ma van gui JSON, mot so client se bo qua no, con mot so khac se hanh xu kho doan. Tuc la ban tu tay tao bug cho minh, roi sau do heroically di sua no.

Heler nhanh “day co phai la thanh cong?”

package main

func is2xx(code int) bool {
	return code >= 200 && code <= 299
}

4. Tinh idempotent: goi lai request — the gioi khong xau hon

Tu “idempotent” nghe nhu duoc sinh ra de doa sinh vien trong bai kiem tra. Trong thuc te, y tuong rat don gian: neu ban goi lai request, tac dong cuoi cung khong duoc thay doi them. Dieu nay khong co nghia la “khong co gi thay doi”. No co nghia la: “goi lai se khong tao ra tac dung phu”.

Vi du ngoai doi: nut “xoa task”. Neu nguoi dung bam hai lan (hoac mang bi giat, client gui lai request), task van phai o trang thai da bi xoa, khong phai “bi xoa hai lan” (neu dieu do co nghia gi).

Tinh idempotent quan trong vi the gioi thuc: mang khong on dinh, ket noi bi dut, client co the khong nhan duoc response va quyet dinh goi lai request. Neu ban thiet ke API sao cho lan goi lai an toan, ban se giam so luong duplicate ky la va cac trang thai “bong ma”.

Quy tac tho so nhu mot uoc luong dau tien

Thuong nguoi ta lam nhu sau: coi GET/PUT/PATCH/DELETE la idempotent, con POST thi khong (vi “tao” hai lan = hai resource). Dieu nay khong phai chan ly tuyet doi, nhung la mot ky luat khoi dau tot.

package main

func isIdempotent(method string) bool {
	switch method {
	case "GET", "PUT", "PATCH", "DELETE":
		return true
	default:
		return false
	}
}

Demo nho de “cam” duoc no

package main

import "fmt"

func main() {
	fmt.Println(isIdempotent("GET"))    // true
	fmt.Println(isIdempotent("POST"))   // false
	fmt.Println(isIdempotent("DELETE")) // true
}

Tat nhien, day khong phai “bao mat API thuc su”. Nhung day la mot cach tot de dung nham idempotency voi “khong thay doi gi ca”.

5. Gan voi domain: ban nhap HTTP contract cho tasks

Bay gio chung ta lam mot buoc quan trong: dich cac tu HTTP truu tuong thanh tu vung cua ung dung. Chung ta da song trong domain tasks tu lau (tasks): them task, xem danh sach, danh dau da xong. Trong phong cach HTTP, chung ta muon path mo ta entity, con method mo ta hanh dong.

Thong nhat rang API duoc version hoa qua path. Dang se la: /api/v1/.... Version trong path la cach noi: “hop dong nay da duoc chot, va neu chung ta phai pham no, chung ta se lam dieu do o version khac, khong phai bat ngo vao thu Sau buoi toi”.

Bang endpoint nhu mot ban nhap hop dong

GET

/api/v1/tasks

200

POST

/api/v1/tasks

201

GET

/api/v1/tasks/{id}

200

PATCH

/api/v1/tasks/{id}/done

DELETE

/api/v1/tasks/{id}

204

Luu y: o day chung ta chua ban ve dinh dang JSON va dinh dang loi thong nhat (day cung la mot phan cua hop dong, nhung la chu de khac). O day chung ta tap trung vao “xuong song”: method, path, status thanh cong — de chung ta khong co POST /getTask va GET /deleteTask. Chung ta viet API sao cho co the doc nhu tieng Anh (hoac nhu mot tieng Anh rat la ky cuc).

Them chut code de co dinh method va khong phai viet chuoi bang tay

Cac chuoi "GET" va "POST" bang tay thi van chay, nhung rat de sai. Vi vay ngay ca tu giai doan dau cung nen tao const.

package main

type Method string

const (
	MethodGet    Method = "GET"
	MethodPost   Method = "POST"
	MethodPut    Method = "PUT"
	MethodPatch  Method = "PATCH"
	MethodDelete Method = "DELETE"
)

Va bay gio endpoint co the duoc mo ta mot cach “co kieu” hon:

package main

type Endpoint struct {
	Method Method
	Path   string
}

var listTasks = Endpoint{Method: MethodGet, Path: "/api/v1/tasks"}
var deleteTask = Endpoint{Method: MethodDelete, Path: "/api/v1/tasks/{id}"}

6. Cac loi thuong gap khi thiet ke HTTP API

Loi so 1: thay doi trang thai qua GET.
Thuong dieu nay xay ra “cho tien”: “thi toi chi mo lien ket thoi...”. Nhung GET la doc. Neu GET thay doi trang thai, ban lam hong cache, lam hong cac request lap lai va lam tat ca client ngai ngu. Den mot luc nao do ban se gap bug “task tu nhien duoc tao” — va do khong phai ma thuat, ma la GET.

Loi so 2: luc nao cung tra 200 va che loi trong text.
Doi khi nguoi ta lam the nay: status 200, ben trong JSON co field "error": "...". Voi client, dieu nay rat te: no phai parse body de biet thanh cong hay khong. Cach dung hon la thanh cong thi 2xx, loi request thi 4xx, con loi noi bo server thi 5xx. Body loi co the co cau truc, nhung status code la dau hieu dau tien.

Loi so 3: nham lan 400 va 404.
Neu client gui id = "abc" va ban khong the phan tich no thanh so — do khong phai la “khong tim thay”, do la “request khong hop le”, tuc 400. Con 404 la khi id hop le, nhung resource do khong ton tai. Su khac biet nay giup client va test de tho hon nhieu.

Loi so 4: tra body response voi 204.
204 co nghia la “thanh cong, nhung khong co body”. Neu ban van gui JSON, mot so client se bo qua. Ket qua la mot API “doi luc hoat dong”. Va “doi luc hoat dong” la mot kieu dau rat kho chiu, vi khong co gi de debug: no chi la “doi luc”.

Loi so 5: khong nghi ve idempotency va cac lan goi lai.
Trong the gioi thuc, request bi goi lai thuong xuyen. Neu ban thiet ke thao tac sao cho lan goi lai DELETE bat ngo tro thanh 500, hoac lan goi lai PATCH tao ra thay doi trung lap, thi client se so retry, con ban se phai dieu tra cac trang thai “la”. Idempotency khong phai trang tri, ma la lop bao hiem cho thuc te mang.

1

Nhiệm vụ

Go SELF, mức độ, bài học

Đã khóa

Lớp phản hồi

Lớp phản hồi

Mở

1

Nhiệm vụ

Go SELF, mức độ, bài học

Đã khóa

Phương thức idempotent

Phương thức idempotent

Mở

1

Nhiệm vụ

Go SELF, mức độ, bài học

Đã khóa

Bản nháp hợp đồng

Bản nháp hợp đồng

Mở

1

Nhiệm vụ

Go SELF, mức độ, bài học

Đã khóa

Trình mô phỏng hợp đồng

Trình mô phỏng hợp đồng

Mở