Đặt tên REST API, event, Kafka topic, env var và git branch Cơ bản

Trang này trả lời: những cái tên ra khỏi process (endpoint, JSON, event, topic, env var, branch) nên đặt thế nào. Đây là hợp đồng với người khác, nên đổi tên sau này rất đắt.

REST API: danh từ số nhiều, động từ chỉ cho action

Quy tắc	Trước	Sau
Collection là danh từ số nhiều	GET /getOrders, GET /order	GET /orders
Path segment nhiều từ	/paymentMethods, /payment_methods	/payment-methods
JSON field camelCase, viết tắt như một từ	{ "order_ID": 1, "CustomerName": "..." }	{ "orderId": 1, "customerName": "..." }
CRUD dùng HTTP method	POST /orders/delete/42	DELETE /orders/42
Action không phải CRUD	POST /orders/42/do-cancel-order	POST /orders/42:cancel hoặc POST /orders/42/cancel
Danh sách	POST /api/getOrderList	GET /api/orders

Hai guideline lớn không thống nhất ở path segment:

	Microsoft Azure REST Guidelines	Google AIP-122 / AIP-136
Path segment	kebab-case (ưu tiên) hoặc camelCase	collection ID camelCase số nhiều (publishers/123/books)
JSON field	camelCase	AIP-140: lower_snake_case trong proto, được map sang quy ước của JSON
Action	POST /<collection>/<id>:<action>, chỉ khi CRUD không diễn tả được	custom method :archive, GET hoặc POST

Đề xuất mặc định cho API công khai HTTP/JSON: path kebab-case, JSON camelCase. Quan trọng hơn lựa chọn là một API chỉ dùng một kiểu. Error body cũng cần tên field ổn định: xem Problem Details RFC 9457.

Event và topic

Event là một sự thật đã xảy ra: đặt ở thì quá khứ, theo ngôn ngữ domain (OrderPlaced, PaymentCaptured). Tên mệnh lệnh như CreateInvoice là command: nó yêu cầu một việc, và có thể bị từ chối.

Đang tải diagram…

Trước	Vấn đề	Sau
OrderUpdated	Không nói gì đã đổi; consumer phải diff	OrderShippingAddressChanged
PaymentEvent với field type	Một tên cho mọi thứ	PaymentCaptured, PaymentRefunded
SendEmail trên topic event	Là command, không phải event	CustomerRegistered (email service tự quyết gửi)
order_status_9	Mã nội bộ lộ ra ngoài	OrderCancelled

Topic là quy ước team, Kafka không bắt buộc cấu trúc. Một mẫu dễ vận hành: <domain>.<event-hoặc-entity>.v<major>, ví dụ billing.payment-captured.v1. Version trong tên cho phép chạy song song v1 và v2 khi schema đổi không tương thích.

Ràng buộc thật từ Kafka (theo Topic.java):

• Chỉ ký tự [a-zA-Z0-9._-], tối đa 249 ký tự.
• Topic khác nhau chỉ ở . và _ cùng vị trí có thể trùng tên metric. Chọn một dấu phân cách và không trộn.

Cách chọn key cho topic xem Kafka message key và thứ tự.

Env var

POSIX quy định biến môi trường của các tiện ích chuẩn chỉ gồm chữ hoa, chữ số, _ và không bắt đầu bằng số. Theo cùng kiểu đó, thêm prefix theo nhóm và hậu tố đơn vị:

# Trước
dbHost=...
TIMEOUT=30
KEY=sk_live_...

# Sau
DATABASE_URL=postgres://...
PAYMENT_API_TIMEOUT_MS=30000
PAYMENT_API_SECRET_KEY=...
FEATURE_NEW_CHECKOUT_ENABLED=true

• Prefix (PAYMENT_, FEATURE_): gom nhóm khi validate config lúc khởi động, dễ grep.
• Hậu tố đơn vị (_MS, _BYTES): cùng lý do như trong code.

Một chữ 'timeout' và 30 phút retry

Một service đọc TIMEOUT=30 từ env. Thư viện HTTP hiểu là mili giây, người cấu hình nghĩ là giây. Mọi call tới cổng thanh toán timeout sau 30 ms, rơi vào retry, và on-call mất nửa giờ nhìn dashboard “payment provider chậm” trước khi đọc tới dòng config.

Cách sửa không phải thêm comment. Đổi tên thành PAYMENT_API_TIMEOUT_MS, validate khoảng hợp lệ lúc khởi động (ví dụ 100 đến 60.000), và app từ chối chạy nếu giá trị ngoài khoảng.

Git branch

Mẫu: loại/mã-ticket-mô-tả-ngắn, chữ thường, gạch ngang.

Branch	Ý nghĩa
feat/PAY-210-partial-refund	Tính năng mới, ticket PAY-210
fix/ORD-88-duplicate-webhook	Sửa lỗi, ticket ORD-88
chore/bump-node-24	Việc bảo trì

Mã ticket nối branch với lý do thay đổi; loại (feat, fix, chore) giúp lọc trong CI. Quy trình branch đầy đủ xem Git workflow.

Tiếp theo: Lỗi hay gặp.