Đặt tên trong backend: code, database, API và event Cơ bản

Cụm này trả lời: đặt tên thế nào cho code, bảng, endpoint, event để người đọc sau không phải đoán, và chỗ nào là chuẩn kỹ thuật, chỗ nào chỉ là quy ước team.

Vấn đề

Một PR có hàm processData(data, flag), bảng tblOrderInfo, cột CreatedDate, topic order-topic. Code chạy đúng, nhưng reviewer phải mở ba file mới biết flag là gì và cột kia lưu giờ theo múi nào.

Code được đọc nhiều hơn viết rất nhiều lần. Tên cũng là ngôn ngữ của domain: business nói “đơn bị huỷ”, code nói deleted, database nói status = 9, event nói OrderRemoved thì mỗi cuộc họp cần một người phiên dịch. Xem Bounded Context.

Đọc theo thứ tự nào

Đang tải diagram…

Trong cụm này

Phần	Trả lời câu hỏi
Quy tắc cốt lõi	Sáu quy tắc chung là gì? TypeScript và NestJS đặt tên file, class, DTO ra sao?
PostgreSQL	Vì sao snake_case? Giới hạn 63 byte? Tên constraint/index mặc định là gì?
API, event, env	Path REST, JSON field, event, Kafka topic, env var, git branch đặt thế nào?
Lỗi hay gặp	Những cái tên nào gây bug thật, và checklist review?

Bảng quyết định: casing nào ở đâu

Nơi	Quy ước	Ví dụ	Căn cứ
Biến, hàm, method, property (TS)	lowerCamelCase	orderTotal, findOrderById	Google TS Style Guide
Class, interface, type, enum, decorator	UpperCamelCase	OrderService, PaymentStatus	Google TS Style Guide
Hằng số cấp module, giá trị enum	CONSTANT_CASE	MAX_RETRY_ATTEMPTS	Google TS Style Guide
File NestJS	kebab-case.<loại>.ts	orders.controller.ts, create-order.dto.ts	Ví dụ trong docs NestJS
Bảng, cột, constraint, index (PostgreSQL)	snake_case, chỉ a-z 0-9 _	order_items, created_at	Case folding của PostgreSQL
Path segment REST	kebab-case, danh từ số nhiều	/payment-methods/{id}	Microsoft REST Guidelines
JSON field	camelCase	{ "orderId": "..." }	Microsoft REST Guidelines
Tên event	UpperCamelCase, quá khứ	OrderPaid	Quy ước team
Kafka topic	lowercase, dấu chấm phân tầng	billing.order-paid.v1	Quy ước team, ký tự theo Kafka
Env var	UPPER_SNAKE_CASE, có prefix	PAYMENT_API_TIMEOUT_MS	POSIX
Git branch	loại/ticket-mô-tả	fix/PAY-142-refund-rounding	Quy ước team

Chỗ nào có chuẩn hoặc ràng buộc kỹ thuật thì theo chuẩn. Chỗ nào là quy ước team thì chọn một lần, ghi vào README, cho linter kiểm.

Khi nào áp dụng, khi nào là ngoại lệ

Áp dụng ngay cho mọi code, bảng, endpoint và topic mới. Ngoại lệ hợp lý:

• Codebase có quy ước cũ nhất quán: nhất quán quan trọng hơn “đúng”. Đừng trộn IFoo và Foo trong một repo; đổi cả repo một lần hoặc giữ nguyên.
• Hợp đồng đã public (endpoint, JSON field, topic, cột team khác dùng): đổi tên là breaking change, cần version mới hoặc chạy song song.
• Tên do bên ngoài quy định (webhook đối tác, header HTTP, claim sub, exp của JWT): giữ nguyên ở biên, map sang tên của bạn ngay sau đó.
• Domain đã có thuật ngữ: nghiệp vụ gọi là settlement thì đừng đổi thành payout cho “dễ hiểu”.

Tóm tắt

Tóm tắt

• Tên được đọc nhiều hơn viết; tối ưu cho người đọc sau, và dùng ngôn ngữ của domain.
• Một từ cho một khái niệm; boolean là câu hỏi không phủ định; số có đơn vị.
• TypeScript theo Google TS Style Guide: không I prefix, không _ private, viết tắt như một từ.
• PostgreSQL: chỉ a-z 0-9 _, tối đa 63 byte, đặt tên constraint và index tường minh.
• API: danh từ số nhiều, một kiểu casing cho path và JSON; event ở thì quá khứ, topic có domain và version.
• Nhất quán thắng “đúng”; hợp đồng đã public thì đổi tên bằng migration, không bằng refactor.

Tiếp theo: Quy tắc cốt lõi.