Tối ưu hiệu năng Go + Postgres: sổ tay thực tế cho API

Trông "chậm" thế nào với API Go trên Postgres

API sinh bởi AI có thể cảm thấy nhanh khi test ban đầu. Bạn gọi endpoint vài lần, dataset nhỏ, và request đến một lần một. Rồi traffic thực đến: nhiều endpoint hỗn hợp, tải đột biến, cache lạnh hơn, và nhiều hàng hơn bạn nghĩ. Cùng mã đó có thể bắt đầu cảm thấy ngẫu nhiên chậm mặc dù không có gì thực sự hỏng.

Chậm thường xuất hiện theo vài cách: spike độ trễ (đa số request ổn, một vài request chậm hơn 5x–50x), timeout (một phần nhỏ thất bại), hoặc CPU chạy cao (CPU Postgres vì truy vấn, hoặc CPU Go vì JSON, goroutine, logging và retry).

Một kịch bản phổ biến là endpoint danh sách với bộ lọc linh hoạt trả về JSON lớn. Trong DB test, nó quét vài nghìn hàng và xong nhanh. Trong production, nó quét vài triệu hàng, sắp xếp, và chỉ sau đó áp LIMIT. API vẫn "hoạt động", nhưng p95 latency phóng lên và vài request timeout khi có đợt burst.

Để tách chậm do DB và chậm do app, giữ mô hình tinh thần đơn giản.

Nếu database chậm, handler Go dành phần lớn thời gian chờ truy vấn. Bạn cũng có thể thấy nhiều request bị kẹt "in flight" trong khi CPU Go trông bình thường.

Nếu app chậm, truy vấn xong nhanh nhưng thời gian bị tiêu tốn sau truy vấn: xây response object lớn, marshal JSON, chạy thêm truy vấn cho từng hàng, hoặc làm quá nhiều việc cho mỗi request. CPU Go tăng, bộ nhớ tăng, và độ trễ tăng theo kích thước phản hồi.

Hiệu năng "đủ tốt" trước khi ra mắt không cần hoàn hảo. Với nhiều endpoint CRUD, mục tiêu là p95 ổn định (không chỉ trung bình), hành vi dự đoán được khi burst, và không timeout ở mức tải kỳ vọng. Mục tiêu đơn giản: không có request chậm bất ngờ khi dữ liệu và traffic tăng, và tín hiệu rõ ràng khi có drift.

Bắt đầu từ baseline: vài con số quan trọng

Trước khi tối ưu, quyết định xem "tốt" nghĩa là gì cho API của bạn. Không có baseline, dễ mất hàng giờ thay đổi cài đặt mà vẫn không biết mình có cải thiện hay chỉ dịch nút cổ chai.

Ba con số thường cho bạn phần lớn câu chuyện:

• p95 request latency (không phải trung bình)
• tỷ lệ lỗi (HTTP 5xx, timeout, request bị huỷ)
• thời gian DB trên mỗi request (mỗi request chờ Postgres bao lâu)

p95 là chỉ số cho "ngày tồi". Nếu p95 cao mà trung bình ổn, một tập nhỏ request đang làm quá nhiều việc, bị chặn bởi lock, hoặc kích hoạt kế hoạch chậm.

Làm cho các truy vấn chậm hiển hiện sớm. Trong Postgres, bật logging truy vấn chậm với ngưỡng thấp cho kiểm thử trước lúc ra mắt (ví dụ 100–200 ms), và log đầy đủ statement để bạn có thể copy vào client SQL. Giữ việc này tạm thời. Log mọi truy vấn chậm trong production sẽ nhanh chóng ồn ào.

Tiếp theo, test với request giống thực tế, không chỉ một route "hello world". Một tập nhỏ đủ nếu nó khớp hành vi người dùng: một gọi danh sách với filter và sort, một trang chi tiết với vài join, một create/update có validate, và một truy vấn kiểu search với partial match.

Nếu bạn sinh endpoint từ spec (ví dụ với công cụ vibe-coding như Koder.ai), chạy cùng vài request đó lặp lại với input cố định. Điều đó làm cho các thay đổi như chỉ mục, tinh chỉnh phân trang, và viết lại truy vấn dễ đo hơn.

Cuối cùng, chọn mục tiêu bạn có thể nói thành tiếng. Ví dụ: 'Phần lớn request giữ dưới 200 ms p95 ở 50 user đồng thời, và lỗi dưới 0.5%.' Số cụ thể tuỳ sản phẩm, nhưng mục tiêu rõ ràng ngăn việc tinh chỉnh vô tận.

Pool kết nối giữ Postgres ổn định

Pool kết nối giữ một số lượng kết nối DB mở giới hạn và tái sử dụng chúng. Không có pool, mỗi request có thể mở kết nối mới, và Postgres tốn thời gian và bộ nhớ quản lý session thay vì chạy truy vấn.

Mục tiêu là giữ Postgres bận rộn làm việc có ích, không chuyển ngữ cảnh giữa quá nhiều kết nối. Đây thường là lợi ích thiết thực đầu tiên, đặc biệt cho API sinh bởi AI có thể lặng lẽ trở thành các endpoint hay gọi.

Cài đặt khởi đầu đơn giản

Trong Go, bạn thường điều chỉnh max open connections, max idle connections, và lifetime của kết nối. Điểm khởi đầu an toàn cho nhiều API nhỏ là một bội số nhỏ của CPU cores (thường 5 đến 20 kết nối tổng), với số idle tương tự, và tái chế kết nối định kỳ (ví dụ mỗi 30–60 phút).

Nếu chạy nhiều instance API, nhớ pool nhân lên. Pool 20 kết nối trên 10 instance là 200 kết nối chạm Postgres, và đây là lý do các team bất ngờ gặp giới hạn kết nối.

Cách biết pool là vấn đề

Vấn đề pool khác với SQL chậm.

Nếu pool quá nhỏ, request chờ trước khi tới Postgres. Latency spike, nhưng CPU DB và thời gian truy vấn có thể trông ổn.

Nếu pool quá lớn, Postgres trông quá tải: nhiều session active, áp lực bộ nhớ, và độ trễ không đều giữa các endpoint.

Cách nhanh để tách hai thứ là đo thời gian cuộc gọi DB thành hai phần: thời gian chờ kết nối vs thời gian thực thi truy vấn. Nếu phần lớn là "chờ", pool là nút cổ chai. Nếu phần lớn là "trong truy vấn", tập trung vào SQL và chỉ mục.

Kiểm tra nhanh hữu ích:

• Log stats pool (open, in-use, idle) và theo dõi in-use bị dính ở max.
• Thêm timeout khi lấy kết nối để chờ thất bại nhanh ở staging.
• Giám sát kết nối active trong Postgres và gần tới max_connections thế nào.
• Xác nhận mỗi request đóng rows và trả kết nối ngay.
• Load test với cùng số instance app bạn định chạy.

pgx pool vs database/sql

Nếu bạn dùng pgxpool, bạn có pool ưu tiên Postgres với stats rõ ràng và mặc định tốt cho hành vi Postgres. Nếu bạn dùng database/sql, bạn có interface chuẩn làm việc đa DB, nhưng cần cấu hình rõ ràng về pool và hành vi driver.

Quy tắc thực tế: nếu bạn chỉ dùng Postgres và muốn kiểm soát trực tiếp, pgxpool thường đơn giản hơn. Nếu bạn phụ thuộc thư viện mong database/sql, giữ lại và đặt pool rõ ràng, đo các lần chờ.

Ví dụ: một endpoint liệt kê orders có thể chạy trong 20 ms, nhưng dưới 100 concurrent user nhảy lên 2 s. Nếu log cho thấy 1.9 s là thời gian chờ connection, tuning query không giúp cho tới khi pool và tổng kết nối Postgres được cỡ hoá đúng.

Kế hoạch truy vấn: đọc nhanh output EXPLAIN

Khi một endpoint cảm thấy chậm, kiểm tra Postgres đang làm gì. Đọc nhanh EXPLAIN thường chỉ ra fix trong vài phút.

Chạy cái này trên đúng SQL mà API gửi:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, status, created_at
FROM orders
WHERE user_id = $1 AND status = $2
ORDER BY created_at DESC
LIMIT 50;

Một vài dòng quan trọng nhất. Nhìn node trên cùng (Postgres chọn gì) và tổng ở dưới cùng (mất bao lâu). So sánh estimated vs actual rows. Khoảng cách lớn thường nghĩa planner đoán sai.

Những dòng quan trọng thường có nghĩa gì

Nếu bạn thấy Index Scan hoặc Index Only Scan, Postgres đang dùng chỉ mục, thường là tốt. Bitmap Heap Scan có thể ổn cho khớp kích thước trung bình. Seq Scan nghĩa đọc toàn bộ bảng, chỉ ổn khi bảng nhỏ hoặc hầu hết hàng khớp.

Cảnh báo phổ biến:

• Seq Scan trên bảng lớn
• Estimated rows vs actual rows cách xa (ví dụ 10 ước tính vs 10.000 thực tế)
• Sort chiếm phần lớn thời gian (thường kèm ORDER BY)
• "Filter:" loại bỏ nhiều hàng sau khi quét
• Nhiều shared read blocks trong BUFFERS (đọc nhiều dữ liệu)

Tại sao plan sai (và cách sửa dễ)

Plan chậm thường đến từ vài pattern:

• Thiếu chỉ mục cho pattern WHERE + ORDER BY của bạn (ví dụ (user_id, status, created_at))
• Kiểu dữ liệu không khớp (ví dụ so sánh UUID với tham số text), chặn dùng chỉ mục
• Hàm trong WHERE (ví dụ WHERE lower(email) = $1), khiến phải scan trừ khi thêm expression index tương ứng

Nếu plan lạ và estimate sai nhiều, stats thường lỗi thời. Chạy ANALYZE (hoặc để autovacuum bắt kịp) để Postgres học số lượng hàng và phân bố giá trị hiện tại. Điều này quan trọng sau import lớn hoặc khi endpoint mới bắt đầu viết nhiều dữ liệu nhanh.

Chỉ mục cho truy vấn bạn thực sự chạy

Chỉ mục chỉ giúp khi khớp với cách API truy vấn dữ liệu. Nếu tạo từ dự đoán, bạn sẽ có write chậm hơn, lưu trữ lớn hơn, và ít cải thiện.

Cách nghĩ thực tế: chỉ mục là đường tắt cho một câu hỏi cụ thể. Nếu API hỏi câu khác, Postgres bỏ qua đường tắt đó.

Xây chỉ mục quanh filter + thứ tự sắp xếp

Nếu endpoint lọc theo account_id và sắp theo created_at DESC, một chỉ mục tổng hợp thường tốt hơn hai chỉ mục riêng. Nó giúp Postgres tìm hàng đúng và trả chúng theo thứ tự với ít việc hơn.

Nguyên tắc hay giữ vững:

• Chỉ mục các cột bạn lọc nhiều nhất, rồi thêm cột bạn sắp xếp.
• Giữ chỉ mục tổng hợp nhỏ. Hai cột phổ biến; ba đôi khi OK; nhiều hơn thường là ám hiệu.
• Đặt filter chọn lọc nhất trước.
• Tránh các chỉ mục riêng mà bị phủ bởi một chỉ mục tổng hợp tốt hơn.
• Ưu tiên một chỉ mục được chọn tốt thay vì vài cái "có thể hữu ích".

Ví dụ: nếu API có GET /orders?status=paid và luôn hiển thị mới nhất trước, chỉ mục như (status, created_at DESC) là phù hợp. Nếu phần lớn query cũng lọc theo customer, (customer_id, status, created_at) có thể tốt hơn, nhưng chỉ nếu đó là cách endpoint chạy thực tế trong production.

Chỉ mục partial cho các filter phổ biến

Nếu phần lớn traffic nhắm vào một lát hẹp của hàng, partial index có thể rẻ và nhanh hơn. Ví dụ, nếu app chủ yếu đọc record active, chỉ đánh chỉ mục WHERE active = true giữ index nhỏ hơn và dễ ở trong bộ nhớ.

Để xác nhận index hữu ích:

• Chạy EXPLAIN (hoặc EXPLAIN ANALYZE ở môi trường an toàn) và tìm index scan phù hợp.
• So sánh thời gian và số hàng đọc với và không có chỉ mục.
• Theo dõi "Rows Removed by Filter" còn cao không. Thường nó nghĩa index không khớp filter.

Xoá chỉ mục không dùng cẩn trọng. Kiểm tra stats usage (chẳng hạn index có bị scan hay không). Drop từng cái một trong cửa sổ rủi ro thấp, và có kế hoạch rollback. Chỉ mục không dùng không vô hại — chúng làm chậm insert và update trên mọi ghi.