@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/backup.js +106 -4
- package/dist/bridges.d.ts +26 -0
- package/dist/bridges.js +96 -0
- package/dist/gate-ledger.d.ts +30 -0
- package/dist/gate-ledger.js +99 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2 -0
- package/dist/library-edit.d.ts +57 -5
- package/dist/library-edit.js +216 -11
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/migrations.js +1 -1
- package/dist/models.d.ts +74 -0
- package/dist/models.js +67 -1
- package/dist/packaged.d.ts +122 -0
- package/dist/packaged.js +125 -0
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +6 -6
- package/dist/providers.d.ts +4 -5
- package/dist/providers.js +26 -5
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/task-rows.d.ts +5 -0
- package/dist/task-rows.js +1 -1
- package/dist/tasks.d.ts +23 -4
- package/dist/tasks.js +103 -9
- package/dist/types.d.ts +3 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/user-worktree.d.ts +29 -0
- package/dist/user-worktree.js +242 -0
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +35 -13
- package/package.json +34 -2
- package/src/backup.js +106 -5
- package/src/bridges.js +113 -0
- package/src/gate-ledger.js +125 -0
- package/src/index.js +1 -0
- package/src/library-edit.js +227 -12
- package/src/library.js +96 -6
- package/src/migrations.js +1 -1
- package/src/models.js +87 -1
- package/src/packaged.js +207 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +7 -7
- package/src/providers.js +23 -7
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/task-rows.js +1 -1
- package/src/tasks.d.ts +23 -4
- package/src/tasks.js +137 -10
- package/src/types.d.ts +3 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/user-worktree.js +259 -0
- package/src/validation.d.ts +1 -0
- package/src/validation.js +43 -14
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -141
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +34 -0
- package/templates/skills/curate/SKILL.md +36 -0
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Thiết kế API
|
|
2
|
+
|
|
3
|
+
Đọc khi thiết kế một resource hoặc endpoint mới, hoặc khi chọn status code,
|
|
4
|
+
phân trang, idempotency, versioning, hay validation cho request.
|
|
5
|
+
|
|
6
|
+
Kiểu API hiện có của dự án thắng. Nếu dự án dùng route kiểu RPC, GraphQL, hay gRPC,
|
|
7
|
+
hãy áp dụng tinh thần của các quy tắc dưới đây (resource rõ ràng, contract ổn định,
|
|
8
|
+
lỗi tường minh) theo kiểu đó thay vì chuyển nó sang REST.
|
|
9
|
+
|
|
10
|
+
## Resource và route
|
|
11
|
+
|
|
12
|
+
- Đặt tên resource là danh từ số nhiều: `/orders`, `/orders/{id}`, `/orders/{id}/items`.
|
|
13
|
+
- Chỉ lồng nhau khi thật sự là quan hệ sở hữu, nhiều nhất một hoặc hai cấp.
|
|
14
|
+
- Dùng method theo ý định: GET đọc (an toàn), PUT thay thế (idempotent), PATCH cập
|
|
15
|
+
nhật một phần, POST tạo hoặc chạy một hành động, DELETE xóa (idempotent).
|
|
16
|
+
- Mô hình hóa một hành động không phải CRUD thành sub-resource hoặc một POST tới hành
|
|
17
|
+
động có tên (`POST /orders/{id}/cancel`) khi dự án đã làm như vậy.
|
|
18
|
+
- Giữ cách đặt tên field nhất quán với các response hiện có (camelCase hay snake_case).
|
|
19
|
+
- Trả về biểu diễn đã tạo hoặc đã cập nhật, hoặc theo quy ước hiện có.
|
|
20
|
+
- Dùng ID mờ hoặc không tăng tuần tự trong URL khi việc dò tuần tự làm lộ thông tin.
|
|
21
|
+
|
|
22
|
+
## Status code
|
|
23
|
+
|
|
24
|
+
| Tình huống | Code |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| Đọc hoặc cập nhật thành công | 200 |
|
|
27
|
+
| Đã tạo | 201, kèm header Location nếu dự án dùng |
|
|
28
|
+
| Nhận để xử lý bất đồng bộ | 202, kèm cách poll trạng thái |
|
|
29
|
+
| Thành công, không có body | 204 |
|
|
30
|
+
| Input sai dạng hoặc không hợp lệ | 400 hoặc 422, theo quy ước của dự án |
|
|
31
|
+
| Chưa authenticate | 401 |
|
|
32
|
+
| Đã authenticate nhưng không được phép | 403, hoặc 404 để không tiết lộ sự tồn tại |
|
|
33
|
+
| Không tìm thấy | 404 |
|
|
34
|
+
| Xung đột trạng thái, trùng lặp, lệch version | 409 (hoặc 412 cho precondition) |
|
|
35
|
+
| Bị giới hạn tần suất | 429, kèm Retry-After khi biết |
|
|
36
|
+
| Server lỗi bất ngờ | 500 |
|
|
37
|
+
| Dependency không khả dụng hoặc timeout | 502, 503, hay 504 |
|
|
38
|
+
|
|
39
|
+
Không bao giờ trả 200 với body là lỗi. Không bao giờ trả 500 cho input client sai.
|
|
40
|
+
|
|
41
|
+
## Body của lỗi
|
|
42
|
+
|
|
43
|
+
Dùng một hình dạng lỗi duy nhất ở mọi nơi. Nếu dự án chưa có, chỉ cần một code ổn
|
|
44
|
+
định máy đọc được, một message cho người, và chi tiết field tùy chọn, ví dụ
|
|
45
|
+
`{ "error": { "code": "validation_failed", "message": "...", "fields": {...} } }`.
|
|
46
|
+
Một số dự án dùng problem details của RFC 9457; hãy theo cái đang có.
|
|
47
|
+
|
|
48
|
+
## Phân trang
|
|
49
|
+
|
|
50
|
+
- Phân trang theo cursor (keyset) cho tập dữ liệu lớn hoặc hay thay đổi: trả về một
|
|
51
|
+
cursor `next` mờ, dẫn xuất từ khóa sắp xếp cộng một khóa phá thế bằng duy nhất.
|
|
52
|
+
- Phân trang theo offset chỉ dùng cho tập nhỏ, ổn định, hoặc khi client cần số trang;
|
|
53
|
+
nó chậm dần và bỏ sót hoặc lặp dòng khi có ghi đồng thời.
|
|
54
|
+
- Luôn chặn kích thước trang ở phía server và áp một giá trị mặc định.
|
|
55
|
+
- Làm thứ tự sắp xếp tường minh và tất định.
|
|
56
|
+
- Chỉ trả tổng số khi nó rẻ hoặc bắt buộc; việc đếm có thể đắt.
|
|
57
|
+
|
|
58
|
+
## Lọc và sắp xếp
|
|
59
|
+
|
|
60
|
+
- Lập whitelist các field được lọc và được sắp xếp; đừng bao giờ truyền input thô vào truy vấn.
|
|
61
|
+
- Từ chối các tham số lọc hay sắp xếp không nhận biết được, hoặc bỏ qua chúng, theo quy ước dự
|
|
62
|
+
án.
|
|
63
|
+
|
|
64
|
+
## Idempotency
|
|
65
|
+
|
|
66
|
+
- PUT và DELETE phải idempotent theo thiết kế.
|
|
67
|
+
- Với POST tạo mới hoặc thu phí, hãy nhận một header idempotency key khi client có
|
|
68
|
+
thể retry. Lưu key cùng dấu vết của request và response; phát lại response đã lưu
|
|
69
|
+
khi gặp lại; từ chối một key dùng lại với body khác (409 hoặc 422).
|
|
70
|
+
- Cho key đã lưu một thời hạn. Giới hạn phạm vi theo từng client hoặc user.
|
|
71
|
+
- Handler của webhook và job dedupe theo ID của event hoặc message.
|
|
72
|
+
|
|
73
|
+
## Đồng thời
|
|
74
|
+
|
|
75
|
+
- Với các cập nhật có thể đua nhau, dùng optimistic concurrency: một ETag hoặc field
|
|
76
|
+
version, kèm If-Match hoặc version trong body, và 409 hoặc 412 khi lệch.
|
|
77
|
+
|
|
78
|
+
## Versioning
|
|
79
|
+
|
|
80
|
+
- Ưu tiên thay đổi chỉ thêm vào, tương thích ngược: field tùy chọn mới, endpoint mới.
|
|
81
|
+
- Thay đổi phá vỡ (bỏ hoặc đổi tên field, đổi kiểu hay ý nghĩa, siết validation) cần
|
|
82
|
+
quyết định của owner và một đường migration.
|
|
83
|
+
- Theo lược đồ versioning của dự án (tiền tố path, header, hay không có). Đừng đưa vào
|
|
84
|
+
một lược đồ mới mà không có quyết định.
|
|
85
|
+
- Client nên bỏ qua field không biết; đừng dựa vào thứ tự field.
|
|
86
|
+
|
|
87
|
+
## Validate request
|
|
88
|
+
|
|
89
|
+
- Validate ở biên: kiểu, field bắt buộc, khoảng giá trị, độ dài, định dạng, thuộc tập
|
|
90
|
+
enum, và kích thước body tối đa.
|
|
91
|
+
- Dùng validator hoặc library schema hiện có của dự án; đừng thêm cái khác.
|
|
92
|
+
- Parse thành một giá trị có kiểu hoặc đã chuẩn hóa, rồi chỉ truyền giá trị đó vào trong.
|
|
93
|
+
- Từ chối field không biết khi mass assignment là rủi ro (ví dụ client tự đặt `role`
|
|
94
|
+
hay `ownerId`); đừng bao giờ bind body của request thẳng vào model lưu trữ.
|
|
95
|
+
- Trả về tất cả lỗi field một lượt khi khả thi.
|
|
96
|
+
- Validation không phải authorization; kiểm tra quyền riêng.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Authentication và authorization
|
|
2
|
+
|
|
3
|
+
Đọc khi chạm vào login, session, token, OAuth/OIDC, lưu trữ password, hoặc
|
|
4
|
+
kiểm tra quyền.
|
|
5
|
+
|
|
6
|
+
Dùng library hoặc provider auth hiện có của dự án. Tự viết mật mã, xử lý session, hay
|
|
7
|
+
parse token bằng tay là ngoài phạm vi; thay vào đó hãy đề xuất một library đã được
|
|
8
|
+
thẩm định cho owner. Thay đổi về auth xứng đáng có một lượt security-review.
|
|
9
|
+
|
|
10
|
+
## Session so với token
|
|
11
|
+
|
|
12
|
+
| | Session phía server | Token tự chứa (ví dụ JWT) |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Trạng thái | Bản ghi session trong một store; cookie giữ ID | Claim nằm trong token; xác minh bằng chữ ký |
|
|
15
|
+
| Thu hồi | Xóa bản ghi | Khó; cần hạn ngắn, deny list, hoặc xoay refresh token |
|
|
16
|
+
| Phù hợp | App trình duyệt trên một site | Service-to-service, API dùng bởi nhiều client |
|
|
17
|
+
|
|
18
|
+
- Session trình duyệt: cookie với `HttpOnly`, `Secure`, `SameSite=Lax` hoặc `Strict`,
|
|
19
|
+
thời hạn có giới hạn, và một session ID mới sau khi login hay đổi đặc quyền.
|
|
20
|
+
- Request làm thay đổi trạng thái mà authenticate bằng cookie cần bảo vệ CSRF
|
|
21
|
+
(SameSite cộng một token hoặc kiểm tra origin, theo quy ước của dự án).
|
|
22
|
+
- Token: xác minh chữ ký, thuật toán (đừng bao giờ nhận `none` hay một thuật toán
|
|
23
|
+
ngoài dự kiến), issuer, audience, và hạn dùng ở mọi request. Giữ access token
|
|
24
|
+
sống ngắn; xoay refresh token và phát hiện việc dùng lại.
|
|
25
|
+
- Đừng lưu token ở những nơi script bị tiêm có thể đọc, nếu dự án có thể dùng cookie
|
|
26
|
+
HttpOnly thay thế.
|
|
27
|
+
|
|
28
|
+
## Lưu trữ password
|
|
29
|
+
|
|
30
|
+
- Hash bằng một hàm hash password chậm, có salt: Argon2id, scrypt, hay bcrypt, qua
|
|
31
|
+
library hiện có của dự án. Đừng bao giờ dùng hash nhanh (MD5, SHA-1, SHA-256
|
|
32
|
+
thuần), đừng bao giờ dùng mã hóa có thể giải ngược.
|
|
33
|
+
- So sánh bằng hàm verify của library (thời gian hằng).
|
|
34
|
+
- Hash lại khi login nếu tham số đã được nâng.
|
|
35
|
+
- Giới hạn tần suất cho endpoint login và reset; trả cùng một response cho user không
|
|
36
|
+
tồn tại và cho sai password.
|
|
37
|
+
- Token reset: ngẫu nhiên, dùng một lần, hạn ngắn, lưu dạng đã hash.
|
|
38
|
+
|
|
39
|
+
## OAuth 2.0 và OIDC (mức tổng quan)
|
|
40
|
+
|
|
41
|
+
- Đăng nhập web và mobile: authorization code flow với PKCE. Validate `state` (CSRF)
|
|
42
|
+
và, với OIDC, `nonce`. Đừng dùng implicit flow.
|
|
43
|
+
- Service-to-service: client credentials flow với credential có scope lấy từ config.
|
|
44
|
+
- ID token của OIDC định danh user với client; access token cho phép gọi API. Đừng
|
|
45
|
+
dùng ID token làm access token cho API.
|
|
46
|
+
- Đăng ký redirect URI chính xác; đừng bao giờ nhận một đích redirect từ input của
|
|
47
|
+
user mà không có allowlist.
|
|
48
|
+
- Map danh tính bên ngoài sang user nội bộ theo subject ID ổn định của provider cộng
|
|
49
|
+
issuer, không chỉ theo email.
|
|
50
|
+
|
|
51
|
+
## Đặt authorization ở đâu
|
|
52
|
+
|
|
53
|
+
- Authenticate ở biên (middleware hoặc tương đương) và gắn một danh tính vào context
|
|
54
|
+
của request.
|
|
55
|
+
- Authorize tại nơi đã biết resource: sau khi load nó, kiểm tra người gọi được phép
|
|
56
|
+
tác động lên chính bản ghi đó (chủ sở hữu, tenant, role, hay policy). Chỉ kiểm tra
|
|
57
|
+
role ở mức route thì không chặn được việc truy cập bản ghi của user khác (IDOR).
|
|
58
|
+
- Giới hạn truy vấn theo tenant hoặc chủ sở hữu ngay trong lớp truy cập dữ liệu khi
|
|
59
|
+
dự án là multi-tenant, để một lần quên kiểm tra vẫn fail an toàn.
|
|
60
|
+
- Mặc định từ chối. Endpoint mới không có policy tường minh thì phải không tới được.
|
|
61
|
+
- Giữ việc kiểm tra policy ở một chỗ mà dự án đã dùng (một module policy, decorator,
|
|
62
|
+
hay guard) thay vì rải rác các câu điều kiện.
|
|
63
|
+
- Background job và lời gọi nội bộ hành động với một danh tính hoặc service account
|
|
64
|
+
tường minh; ghi lại nó trong audit log ở nơi dự án lưu chúng.
|
|
65
|
+
|
|
66
|
+
## Secret và config
|
|
67
|
+
|
|
68
|
+
- Khóa ký, client secret, và giá trị pepper đến từ cơ chế secret của dự án. Đừng đọc,
|
|
69
|
+
in, hay commit giá trị của chúng; test dùng khóa test riêng hoặc fake.
|
|
70
|
+
- Đừng bao giờ log credential, token, session ID, hay link reset.
|
|
71
|
+
|
|
72
|
+
## Những kiểm tra cần thêm
|
|
73
|
+
|
|
74
|
+
- Request chưa authenticate bị từ chối (401).
|
|
75
|
+
- User đã authenticate nhưng không có quyền bị từ chối (403 hoặc 404).
|
|
76
|
+
- User A không đọc hay sửa được resource của user B.
|
|
77
|
+
- Token hết hạn, bị sửa, hay sai audience bị từ chối.
|
|
78
|
+
- Logout hoặc thu hồi thực sự kết thúc quyền truy cập.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Xử lý lỗi
|
|
2
|
+
|
|
3
|
+
Đọc khi map lỗi sang response, thêm retry hay timeout, hoặc quyết định
|
|
4
|
+
log những gì.
|
|
5
|
+
|
|
6
|
+
## Phân loại lỗi
|
|
7
|
+
|
|
8
|
+
Phân loại mọi thất bại trước khi quyết định xử lý thế nào.
|
|
9
|
+
|
|
10
|
+
| Lớp | Ví dụ | Xử lý | Response thường dùng |
|
|
11
|
+
| --- | --- | --- | --- |
|
|
12
|
+
| Input không hợp lệ | sai kiểu, thiếu field | từ chối ở biên | 400/422 |
|
|
13
|
+
| Chưa authenticate / bị cấm | thiếu token, sai chủ sở hữu | từ chối, không lộ chi tiết | 401/403/404 |
|
|
14
|
+
| Không tìm thấy | ID không biết | lỗi nghiệp vụ | 404 |
|
|
15
|
+
| Xung đột | trùng lặp, version cũ, chuyển trạng thái không hợp lệ | lỗi nghiệp vụ | 409/412 |
|
|
16
|
+
| Tần suất hoặc quota | client vượt giới hạn | từ chối kèm gợi ý | 429 |
|
|
17
|
+
| Dependency lỗi tạm thời | timeout, mất kết nối, upstream 503 | retry nếu idempotent, nếu không thì đẩy ra | 502/503/504 |
|
|
18
|
+
| Dependency lỗi vĩnh viễn | upstream trả 4xx, config sai | đừng retry; báo động | 500/502 |
|
|
19
|
+
| Bug / vỡ bất biến | null ở chỗ không thể null | fail nhanh, log kèm ngữ cảnh | 500 |
|
|
20
|
+
|
|
21
|
+
- Biểu diễn các thất bại nghiệp vụ dự kiến thành lỗi có kiểu hoặc giá trị kết quả,
|
|
22
|
+
theo mẫu của dự án (exception kèm code, error value trong Go, result type).
|
|
23
|
+
- Đừng dùng exception cho luồng điều khiển bình thường ở nơi dự án không làm vậy.
|
|
24
|
+
- Đừng bao giờ lặng lẽ nuốt một lỗi. Hãy xử lý nó, bọc nó kèm ngữ cảnh rồi đẩy lên,
|
|
25
|
+
hoặc log nó ở biên nơi nó kết thúc.
|
|
26
|
+
|
|
27
|
+
## Map sang response
|
|
28
|
+
|
|
29
|
+
- Map lỗi sang response ở một chỗ (error middleware, exception handler, hay một
|
|
30
|
+
helper dùng chung), không phải trong từng handler.
|
|
31
|
+
- Trả về hình dạng lỗi chuẩn của dự án với một code ổn định.
|
|
32
|
+
- Không phơi nội bộ: không stack trace, SQL, đường dẫn file, hay body của upstream.
|
|
33
|
+
- Đưa một request ID hoặc correlation ID vào response và vào log để có thể truy vết
|
|
34
|
+
một báo cáo.
|
|
35
|
+
- Lỗi không biết trở thành một 500 chung và được log đầy đủ ở phía server.
|
|
36
|
+
|
|
37
|
+
## Timeout
|
|
38
|
+
|
|
39
|
+
- Mọi lời gọi ra ngoài (HTTP, database, cache, queue) đều có timeout. Dùng mặc định
|
|
40
|
+
đã cấu hình của client nếu dự án có; nếu không, hãy đề xuất một giá trị.
|
|
41
|
+
- Lan truyền deadline hoặc tín hiệu hủy của request (context trong Go, AbortSignal
|
|
42
|
+
trong Node, timeout hay task cancellation trong Python) để công việc dừng khi người
|
|
43
|
+
gọi đã bỏ cuộc.
|
|
44
|
+
- Timeout bên trong phải ngắn hơn timeout bên ngoài.
|
|
45
|
+
|
|
46
|
+
## Retry
|
|
47
|
+
|
|
48
|
+
- Chỉ retry các thất bại tạm thời của thao tác idempotent, hoặc thao tác đã được làm
|
|
49
|
+
cho idempotent bằng một key.
|
|
50
|
+
- Giới hạn số lần thử (một số nhỏ), dùng exponential backoff kèm jitter, và tôn trọng
|
|
51
|
+
Retry-After.
|
|
52
|
+
- Chỉ retry ở một lớp; retry xếp lồng nhau nhân tải lên.
|
|
53
|
+
- Đừng retry lỗi validation, auth, hay các lỗi vĩnh viễn khác.
|
|
54
|
+
- Với một dependency cứ fail liên tục, dùng circuit breaker hoặc fallback của dự án
|
|
55
|
+
nếu có; đừng thêm library mới mà không có quyết định.
|
|
56
|
+
- Background job: sau lần thử cuối, chuyển sang trạng thái thất bại hoặc dead-letter
|
|
57
|
+
queue kèm lý do; đừng lặp mãi.
|
|
58
|
+
|
|
59
|
+
## Thất bại một phần
|
|
60
|
+
|
|
61
|
+
- Giữ transaction database ngắn và cục bộ. Đừng gọi service bên ngoài bên trong nó.
|
|
62
|
+
- Khi một lần ghi database và một hiệu ứng bên ngoài (message, email, thanh toán)
|
|
63
|
+
đều phải xảy ra, dùng outbox của dự án hoặc một bước bù; nêu rõ khoảng trống nếu
|
|
64
|
+
không có cả hai.
|
|
65
|
+
- Làm handler an toàn khi chạy lại.
|
|
66
|
+
|
|
67
|
+
## Log mà không lộ secret
|
|
68
|
+
|
|
69
|
+
- Log ở biên nơi một lỗi được xử lý, một lần, với: code lỗi, message, request ID,
|
|
70
|
+
thao tác, các ID không nhạy cảm liên quan, và chuỗi nguyên nhân.
|
|
71
|
+
- Dùng logger và field có cấu trúc của dự án; khớp với các level đang có (lỗi client
|
|
72
|
+
thường là info hoặc warn, lỗi server là error).
|
|
73
|
+
- Đừng bao giờ log: password, token, API key, session ID, header authorization, số
|
|
74
|
+
thẻ đầy đủ, secret từ config, hay toàn bộ body request có thể chứa chúng.
|
|
75
|
+
- Che hoặc bỏ dữ liệu cá nhân (email, điện thoại, địa chỉ) trừ khi policy của dự án
|
|
76
|
+
cho phép.
|
|
77
|
+
- Kiểm tra rằng message lỗi dựng từ response của upstream không vọng lại credential.
|
|
78
|
+
- Đừng log ở level error cho những lỗi client dự kiến; nó che mất sự cố thật.
|
|
79
|
+
|
|
80
|
+
## Những kiểm tra cần thêm
|
|
81
|
+
|
|
82
|
+
- Mỗi lớp lỗi đã map trả về đúng status và code đã ghi trong tài liệu.
|
|
83
|
+
- Một exception bất ngờ trả về 500 chung mà không có chi tiết nội bộ.
|
|
84
|
+
- Một dependency bị timeout tạo ra response đã ghi trong tài liệu trong hạn deadline.
|
|
85
|
+
- Retry dừng sau giới hạn và không retry các lỗi vĩnh viễn.
|
|
86
|
+
- Log của một request auth thất bại không chứa token hay password.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Test backend
|
|
2
|
+
|
|
3
|
+
Đọc khi chọn test handler, service, integration, hay contract cho một thay đổi
|
|
4
|
+
backend. Việc cần test những gì nói chung thuộc test-strategy; đây nói về cách làm ở từng seam.
|
|
5
|
+
|
|
6
|
+
Dùng test runner, fixture và helper hiện có của dự án (ví dụ Jest hay Vitest cho
|
|
7
|
+
Node/TypeScript, pytest cho Python, `go test` cho Go). Đừng thêm framework test hay
|
|
8
|
+
công cụ container mà không có quyết định của owner.
|
|
9
|
+
|
|
10
|
+
## Chọn seam
|
|
11
|
+
|
|
12
|
+
| Seam | Chứng minh | Thay thế bằng |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Unit service / nghiệp vụ | quy tắc nghiệp vụ, ca biên, map lỗi | fake cho store, clock, client |
|
|
15
|
+
| Handler / route | parsing, validation, status code, nối auth, hình dạng lỗi | server in-process; service thật hoặc fake |
|
|
16
|
+
| Integration | truy vấn, transaction, constraint, migration | database thật cùng engine |
|
|
17
|
+
| Contract | hình dạng request và response đã thống nhất với bên tiêu thụ hoặc bên cung cấp | contract đã ghi lại hoặc dựa trên schema |
|
|
18
|
+
| Đầu-cuối | một luồng quan trọng xuyên nhiều process | chỉ trong môi trường test |
|
|
19
|
+
|
|
20
|
+
Đặt phần lớn các ca ở seam rẻ nhất mà vẫn chạy qua nguyên nhân thật. Một bug truy vấn
|
|
21
|
+
cần engine database thật; một quy tắc validation thì không.
|
|
22
|
+
|
|
23
|
+
## Test service
|
|
24
|
+
|
|
25
|
+
- Tiêm dependency (store, clock, bộ sinh ID, client gọi ra ngoài) để test kiểm soát
|
|
26
|
+
được chúng. Một fake viết tay có hành vi thật hơn một mock chỉ ghi lại lời gọi.
|
|
27
|
+
- Phủ từng ca của contract: thành công, từng lỗi nghiệp vụ, giá trị biên, và việc
|
|
28
|
+
chạy lại idempotent.
|
|
29
|
+
- Đóng băng thời gian và ngẫu nhiên thay vì sleep hay assert theo khoảng.
|
|
30
|
+
|
|
31
|
+
## Test handler
|
|
32
|
+
|
|
33
|
+
- Chạy handler qua test client in-process của framework (ví dụ request kiểu
|
|
34
|
+
supertest, test client của FastAPI hay Django, `httptest` trong Go).
|
|
35
|
+
- Assert status, code lỗi, và các field body quan trọng; tránh assert toàn bộ body
|
|
36
|
+
khi chỉ vài field là thuộc contract.
|
|
37
|
+
- Test các đường authentication và authorization: thiếu credential, sai user, sai
|
|
38
|
+
tenant, role đủ quyền.
|
|
39
|
+
- Test các ca validation thất bại, kể cả field quá lớn và field không biết.
|
|
40
|
+
|
|
41
|
+
## Test integration với database thật
|
|
42
|
+
|
|
43
|
+
- Dùng cùng engine và cùng major version như production. SQLite không thay được cho
|
|
44
|
+
hành vi của PostgreSQL hay MySQL (kiểu dữ liệu, locking, lỗi constraint).
|
|
45
|
+
- Chạy nó theo cách dự án đã làm: một test container, một service local, hay một
|
|
46
|
+
service trong CI. Nếu chưa có, hãy đề xuất; đừng tự cài.
|
|
47
|
+
- Áp migration thật lên database test, không dùng schema viết tay.
|
|
48
|
+
- Cô lập các test: một transaction được rollback mỗi test, một schema mới mỗi worker,
|
|
49
|
+
hay truncate giữa các test. Đừng phụ thuộc thứ tự test.
|
|
50
|
+
- Chỉ seed dữ liệu mà một test cần, qua factory hoặc builder, ngay trong test đó.
|
|
51
|
+
- Đừng bao giờ trỏ test vào database dùng chung hay production.
|
|
52
|
+
|
|
53
|
+
## Dependency gọi ra ngoài
|
|
54
|
+
|
|
55
|
+
- Fake HTTP của bên thứ ba ở biên client (một stub server local hoặc công cụ mock
|
|
56
|
+
HTTP của dự án). Đừng gọi service bên ngoài thật trong test.
|
|
57
|
+
- Test cả response timeout và lỗi từ dependency, không chỉ thành công.
|
|
58
|
+
- Dùng credential test hoặc giá trị giả; đừng bao giờ dùng key thật.
|
|
59
|
+
|
|
60
|
+
## Background job
|
|
61
|
+
|
|
62
|
+
- Chạy handler trực tiếp với một message; assert hiệu ứng.
|
|
63
|
+
- Chạy nó hai lần với cùng message; assert không có hiệu ứng lặp.
|
|
64
|
+
- Làm handler fail; assert số lần retry và trạng thái thất bại cuối.
|
|
65
|
+
|
|
66
|
+
## Test contract
|
|
67
|
+
|
|
68
|
+
- Khi một team hay service khác tiêu thụ API, hãy kiểm tra hình dạng đối chiếu với
|
|
69
|
+
schema đã thống nhất (OpenAPI, protobuf, JSON Schema) hoặc consumer contract, dùng
|
|
70
|
+
công cụ hiện có của dự án.
|
|
71
|
+
- Một test contract fail vì thay đổi của bạn nghĩa là một thay đổi phá vỡ; hãy chuyển
|
|
72
|
+
quyết định lên thay vì sửa contract cho pass.
|
|
73
|
+
|
|
74
|
+
## Vệ sinh
|
|
75
|
+
|
|
76
|
+
- Không sleep để đồng bộ; hãy chờ một điều kiện hoặc dùng clock điều khiển được.
|
|
77
|
+
- Không secret thật, dữ liệu cá nhân, hay dump production trong fixture.
|
|
78
|
+
- Một test mới phải fail khi chưa có thay đổi. Nếu nó pass trước khi sửa, nó không
|
|
79
|
+
chứng minh được thay đổi (xem bug-loop).
|
|
80
|
+
- Giữ thời gian chạy test tương xứng; đánh dấu các test integration chậm theo cách dự
|
|
81
|
+
án đã làm.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: databases
|
|
3
|
+
description: "Thiết kế schema, viết migration và backfill an toàn, và tối ưu truy vấn cho database quan hệ (PostgreSQL, MySQL, SQLite) và document store, dùng công cụ hiện có của dự án. Dùng khi thêm bảng hay collection, đổi constraint hay index, migrate dữ liệu, hoặc sửa truy vấn chậm. Không dùng cho logic API hay service (backend-development)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Cơ sở dữ liệu
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Thêm hoặc đổi bảng, cột, collection, constraint, hay index.
|
|
11
|
+
- Viết một migration schema, một backfill dữ liệu, hay một kế hoạch rollback.
|
|
12
|
+
- Chẩn đoán một truy vấn chậm, mẫu N+1, chờ lock, hay deadlock.
|
|
13
|
+
- Chọn biên transaction hoặc mức isolation cho một thao tác dữ liệu.
|
|
14
|
+
- Một cố vấn (advisor) hoặc reviewer chỉ đọc được hỏi để đánh giá một schema hay migration (chỉ
|
|
15
|
+
tư vấn).
|
|
16
|
+
|
|
17
|
+
## Không dùng cho
|
|
18
|
+
|
|
19
|
+
- Endpoint, logic service, auth, hay map lỗi: dùng backend-development.
|
|
20
|
+
- Cấp phát hạ tầng, backup, replication, hay hosting database: dùng devops.
|
|
21
|
+
- Một test fail hay một regression dữ liệu chưa rõ nguyên nhân: dùng bug-loop.
|
|
22
|
+
- Chọn engine database, ORM, hay công cụ migration mới: quyết định của owner.
|
|
23
|
+
|
|
24
|
+
## Điều kiện tiên quyết
|
|
25
|
+
|
|
26
|
+
- Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
|
|
27
|
+
- Engine và major version, lớp ORM hay query, và công cụ migration, đọc từ manifest,
|
|
28
|
+
config, và thư mục migration hiện có.
|
|
29
|
+
- Quy ước migration đang có: cách đặt tên, thứ tự, up/down hay chỉ-tiến, cách
|
|
30
|
+
migration chạy trong test và khi deploy.
|
|
31
|
+
- Một database local hoặc test để thao tác lên. Đừng bao giờ dùng database dùng chung hay
|
|
32
|
+
production.
|
|
33
|
+
|
|
34
|
+
## Quy trình
|
|
35
|
+
|
|
36
|
+
1. Nêu yêu cầu dữ liệu: thực thể, quan hệ, cardinality, field bắt buộc, tính duy nhất,
|
|
37
|
+
thời gian lưu, và các đường đọc và ghi chính.
|
|
38
|
+
2. Đọc schema hiện tại (migration, model, hay một dump của database test), không chỉ
|
|
39
|
+
các model ORM; chúng có thể lệch.
|
|
40
|
+
3. Thiết kế thay đổi. Đặt quy tắc toàn vẹn vào trong database ở nơi engine hỗ trợ:
|
|
41
|
+
NOT NULL, foreign key, unique, check constraint. Đọc
|
|
42
|
+
schema-and-migrations.md.
|
|
43
|
+
4. Lập kế hoạch triển khai cho bảng đang có dữ liệu sống: mở rộng, migrate dữ liệu,
|
|
44
|
+
chuyển code, thu hẹp. Mỗi bước phải an toàn khi cả bản ứng dụng cũ và mới
|
|
45
|
+
cùng chạy.
|
|
46
|
+
5. Đánh giá locking: câu lệnh có ghi lại cả bảng hay giữ một lock mạnh không? Dùng
|
|
47
|
+
dạng online của engine (ví dụ dựng index concurrent trong PostgreSQL) và một lock
|
|
48
|
+
timeout khi công cụ của dự án cho phép.
|
|
49
|
+
6. Viết migration bằng công cụ của dự án. Làm nó đảo được, hoặc ghi lại vì sao nó chỉ
|
|
50
|
+
tiến và cách khôi phục.
|
|
51
|
+
7. Viết backfill thành các bước riêng, chia lô, có thể tiếp tục, không nằm trong
|
|
52
|
+
migration schema khi bảng lớn.
|
|
53
|
+
8. Với việc tối ưu truy vấn, đo trước: ghi lại truy vấn, tham số của nó, và plan.
|
|
54
|
+
Đọc query-performance.md. Đổi một thứ, rồi đo lại trên dữ liệu tương đương.
|
|
55
|
+
9. Chạy migration lên, xuống (nếu được hỗ trợ), rồi lên lại trên một database test,
|
|
56
|
+
sau đó chạy test của dự án.
|
|
57
|
+
10. Handoff: các file migration, thứ tự triển khai, ước lượng lock và thời gian chạy, kế hoạch
|
|
58
|
+
backfill, đường rollback, plan trước và sau cho thay đổi truy vấn, quyết định còn mở.
|
|
59
|
+
|
|
60
|
+
Một agent chỉ đọc chạy bước 1-5 và 8 đối chiếu với đề xuất hoặc schema hiện tại, rồi
|
|
61
|
+
báo các rủi ro và một thiết kế được khuyến nghị thay vì tự sửa.
|
|
62
|
+
|
|
63
|
+
## Ràng buộc
|
|
64
|
+
|
|
65
|
+
- Theo engine, ORM, công cụ migration và cách đặt tên hiện có của dự án trước đã.
|
|
66
|
+
Prisma, Drizzle, SQLAlchemy/Alembic, Django migrations, golang-migrate, hay file SQL
|
|
67
|
+
thuần là ví dụ, không phải khuyến nghị.
|
|
68
|
+
- Không thêm dependency, extension, hay data store mới mà không có quyết định của
|
|
69
|
+
owner. Không tự cài.
|
|
70
|
+
- Đừng bao giờ chạy migration, backfill, hay ghi tạm lên database dùng chung, staging,
|
|
71
|
+
hay production; đó là một bước deploy của người sở hữu nó.
|
|
72
|
+
- Đừng bao giờ sửa một migration đã được áp dụng ngoài database local của bạn;
|
|
73
|
+
hãy thêm một migration mới.
|
|
74
|
+
- Thay đổi phá hủy (xóa hay đổi tên cột hoặc bảng, siết kiểu dữ liệu, xóa dữ liệu)
|
|
75
|
+
cần quyết định tường minh của owner và một kế hoạch rollback đã ghi lại.
|
|
76
|
+
- Đừng đọc credential hay dữ liệu cá nhân thật; dùng dữ liệu test và config ví dụ.
|
|
77
|
+
- Ở trong đường dẫn sở hữu. Skill này không cho quyền deploy hay release.
|
|
78
|
+
|
|
79
|
+
## Kiểm chứng
|
|
80
|
+
|
|
81
|
+
- Migration áp sạch lên một database rỗng và lên một database có dữ liệu đại diện.
|
|
82
|
+
- Migration xuống (nếu được hỗ trợ) phục hồi schema trước đó; lên lại áp được.
|
|
83
|
+
- Test của dự án pass với schema mới.
|
|
84
|
+
- Constraint từ chối đúng dữ liệu không hợp lệ mà nó phải từ chối (một test chứng minh).
|
|
85
|
+
- Với thay đổi về hiệu năng: plan và thời gian trước và sau trên dữ liệu tương đương,
|
|
86
|
+
kèm điều kiện đã ghi lại.
|
|
87
|
+
- Mỗi bước triển khai đều tương thích với bản ứng dụng đang chạy.
|
|
88
|
+
|
|
89
|
+
## Xử lý khi thất bại
|
|
90
|
+
|
|
91
|
+
- Migration fail trên dữ liệu hiện có: dừng, báo mẫu của các dòng vi phạm (không phải
|
|
92
|
+
nội dung của chúng), và đề xuất một bước dọn dẹp hoặc một constraint theo giai đoạn.
|
|
93
|
+
- Một lock hoặc một lần ghi lại dài là không tránh được: báo ước lượng và chuyển lên
|
|
94
|
+
quyết định về cửa sổ bảo trì.
|
|
95
|
+
- Không có database test: báo khoảng trống đó; đừng khai là migration đã chạy.
|
|
96
|
+
- Plan khác nhau giữa dữ liệu local và dữ liệu giống production: hãy nói ra; đừng khái quát
|
|
97
|
+
hóa.
|
|
98
|
+
- Một model ORM và schema thật không khớp: báo chỗ lệch trước khi đổi bên nào.
|
|
99
|
+
|
|
100
|
+
## Tài liệu tham khảo
|
|
101
|
+
|
|
102
|
+
- [references/schema-and-migrations.md](references/schema-and-migrations.md) — đọc khi thiết kế bảng, constraint, hay hình dạng document, hoặc khi lập kế hoạch migration expand/contract, backfill, tính đảo được, hay rủi ro lock (bước 3-7).
|
|
103
|
+
- [references/query-performance.md](references/query-performance.md) — đọc khi thêm index, đọc output EXPLAIN, sửa N+1, phân trang, hay chọn transaction và isolation (bước 8).
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Hiệu năng truy vấn
|
|
2
|
+
|
|
3
|
+
Đọc khi thêm index, đọc output EXPLAIN, sửa N+1, phân trang, hay
|
|
4
|
+
chọn transaction và isolation.
|
|
5
|
+
|
|
6
|
+
Hãy đo trước khi đổi bất cứ thứ gì. Ghi lại chính xác truy vấn kèm tham số của nó
|
|
7
|
+
(query log của ORM hoặc slow-query log của database trong môi trường test), số dòng
|
|
8
|
+
liên quan, và plan. Đo lại trên dữ liệu tương đương sau mỗi thay đổi.
|
|
9
|
+
|
|
10
|
+
## Đọc plan
|
|
11
|
+
|
|
12
|
+
- PostgreSQL: `EXPLAIN (ANALYZE, BUFFERS)`; MySQL: `EXPLAIN ANALYZE` (8.0.18+) hoặc
|
|
13
|
+
`EXPLAIN FORMAT=TREE`; SQLite: `EXPLAIN QUERY PLAN`. ANALYZE chạy thật truy vấn:
|
|
14
|
+
chỉ chạy nó trên database test, và bọc các lệnh ghi trong transaction rồi rollback.
|
|
15
|
+
- Hãy tìm: sequential scan hay full scan trên bảng lớn, số dòng ước lượng lệch xa số
|
|
16
|
+
dòng thực tế (statistics cũ), sort hay hash tràn ra đĩa, nested loop trên input
|
|
17
|
+
lớn, và filter chỉ áp sau khi đã lấy nhiều dòng.
|
|
18
|
+
- Plan phụ thuộc khối lượng dữ liệu và statistics. Một plan trên mười dòng nói lên rất
|
|
19
|
+
ít; hãy dùng khối lượng đại diện hoặc nói rằng kết quả chỉ là tạm thời.
|
|
20
|
+
|
|
21
|
+
## Index
|
|
22
|
+
|
|
23
|
+
- Index các cột dùng trong WHERE có tính chọn lọc, JOIN, và ORDER BY trên bảng lớn.
|
|
24
|
+
- Thứ tự cột trong composite index: cột so sánh bằng trước, rồi cột khoảng hay cột
|
|
25
|
+
sắp xếp. Một index trên (a, b) phục vụ filter theo a, hoặc a và b, không phải b một mình.
|
|
26
|
+
- Một covering index (bao cả các cột được chọn) có thể tránh phải tra lại bảng cho các
|
|
27
|
+
lượt đọc nóng.
|
|
28
|
+
- Index một phần hoặc có filter phù hợp với truy vấn trên một tập con nhỏ (`WHERE
|
|
29
|
+
deleted_at IS NULL`).
|
|
30
|
+
- Hàm áp lên một cột (`lower(email)`) vô hiệu hóa index thường; hãy dùng index trên
|
|
31
|
+
biểu thức hoặc lưu một cột đã chuẩn hóa.
|
|
32
|
+
- Ký tự đại diện ở đầu (`LIKE '%x'`) không dùng được index B-tree; full-text search là
|
|
33
|
+
quyết định của owner nếu cần.
|
|
34
|
+
- Mỗi index làm ghi chậm hơn và chiếm dung lượng. Chỉ xóa index không dùng hay trùng
|
|
35
|
+
lặp khi có bằng chứng là nó không được dùng.
|
|
36
|
+
- Document store: tạo index khớp với hình dạng truy vấn và thứ tự sắp xếp; kiểm tra
|
|
37
|
+
output explain xem có collection scan không.
|
|
38
|
+
|
|
39
|
+
## Truy vấn N+1
|
|
40
|
+
|
|
41
|
+
- Dấu hiệu: một truy vấn cho danh sách, rồi một truy vấn cho mỗi phần tử. Tìm nó trong
|
|
42
|
+
query log hoặc bằng cách đếm số truy vấn trong một test.
|
|
43
|
+
- Sửa bằng eager loading của ORM hoặc một truy vấn `WHERE id IN (...)` theo lô; trong
|
|
44
|
+
GraphQL hay các resolver tương tự, dùng một loader gom lô theo từng request.
|
|
45
|
+
- Thêm một test assert số truy vấn cho endpoint khi dự án có helper cho việc đó.
|
|
46
|
+
- Đừng lấy quá nhiều: chỉ load các cột và quan hệ mà người gọi dùng.
|
|
47
|
+
|
|
48
|
+
## Phân trang
|
|
49
|
+
|
|
50
|
+
- Phân trang keyset: `WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC,
|
|
51
|
+
id DESC LIMIT $n`, dựa trên một index trên cùng các cột đó. Chi phí mỗi trang là hằng.
|
|
52
|
+
- OFFSET quét rồi bỏ các dòng bị nhảy qua; chi phí tăng theo độ sâu. Chấp nhận được
|
|
53
|
+
với tập nhỏ.
|
|
54
|
+
- Luôn đưa một khóa phá thế bằng duy nhất vào thứ tự sắp xếp.
|
|
55
|
+
- `COUNT(*)` chính xác trên bảng lớn thì đắt; hãy dùng ước lượng hoặc bỏ nó khi sản
|
|
56
|
+
phẩm cho phép.
|
|
57
|
+
|
|
58
|
+
## Transaction
|
|
59
|
+
|
|
60
|
+
- Giữ transaction ngắn. Không gọi mạng, không chờ người dùng, không vòng lặp lớn bên trong.
|
|
61
|
+
- Nhóm các lệnh ghi phải cùng thành công hoặc cùng thất bại; không gì khác.
|
|
62
|
+
- Lock các dòng theo một thứ tự nhất quán xuyên các đường code để tránh deadlock;
|
|
63
|
+
retry khi gặp lỗi deadlock hay serialization với số lần có giới hạn.
|
|
64
|
+
- Chỉ dùng `SELECT ... FOR UPDATE` (hoặc `SKIP LOCKED` cho job queue) ở nơi bạn buộc
|
|
65
|
+
phải tuần tự hóa truy cập vào các dòng cụ thể.
|
|
66
|
+
- Transaction chạy lâu chặn vacuum (PostgreSQL) và giữ lock; hãy để mắt tới chúng
|
|
67
|
+
trong các batch job.
|
|
68
|
+
|
|
69
|
+
## Mức isolation
|
|
70
|
+
|
|
71
|
+
| Mức | Ngăn được | Cần để ý |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| Read committed (mặc định của PostgreSQL) | dirty read | non-repeatable read, lost update |
|
|
74
|
+
| Repeatable read (mặc định của MySQL InnoDB) | non-repeatable read | write skew; gap lock của MySQL |
|
|
75
|
+
| Serializable | mọi bất thường | lỗi serialization phải được retry |
|
|
76
|
+
|
|
77
|
+
- Với đọc-sửa-ghi, hãy ưu tiên một cập nhật nguyên tử (`SET n = n + 1`), một cập nhật
|
|
78
|
+
có điều kiện kèm kiểm tra version, hoặc một row lock, hơn là nâng isolation toàn cục.
|
|
79
|
+
- SQLite tuần tự hóa các bên ghi; transaction ghi dài chặn các bên ghi khác.
|
|
80
|
+
|
|
81
|
+
## Các kiểm tra khác
|
|
82
|
+
|
|
83
|
+
- Luôn dùng truy vấn tham số hóa; chúng còn cho phép tái dùng plan.
|
|
84
|
+
- Kích thước connection pool nên vừa với giới hạn của database; nhiều kết nối hơn có
|
|
85
|
+
thể chậm hơn.
|
|
86
|
+
- Tránh `SELECT *` trên bảng rộng ở các đường nóng.
|
|
87
|
+
- Chỉ cache khi có một quy tắc vô hiệu hóa đã nêu rõ và có sự đồng thuận của owner.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Schema và migration
|
|
2
|
+
|
|
3
|
+
Đọc khi thiết kế bảng, constraint, hay hình dạng document, hoặc khi lập kế hoạch
|
|
4
|
+
migration expand/contract, backfill, tính đảo được, hay rủi ro lock.
|
|
5
|
+
|
|
6
|
+
## Đánh đổi khi chuẩn hóa
|
|
7
|
+
|
|
8
|
+
- Bắt đầu ở dạng chuẩn hóa (khoảng dạng chuẩn thứ ba): mỗi dữ kiện lưu một lần, liên
|
|
9
|
+
kết bằng khóa. Nó giữ việc ghi đơn giản và ngăn các bất thường khi cập nhật.
|
|
10
|
+
- Chỉ phi chuẩn hóa cho một nhu cầu đọc đã đo được: một bộ đếm, một tổng hợp được
|
|
11
|
+
cache, một field sao chép để tránh một join nóng. Ghi lại ai giữ bản sao đồng bộ
|
|
12
|
+
(trigger, cùng transaction, hay một job) và cách phát hiện lệch.
|
|
13
|
+
- Dùng cột JSON cho các thuộc tính thật sự không có schema hoặc thưa, không phải để
|
|
14
|
+
khỏi phải thiết kế các cột được truy vấn, lọc, hay ràng buộc.
|
|
15
|
+
- Document store: hình dạng document theo mẫu truy cập. Nhúng dữ liệu được đọc cùng
|
|
16
|
+
nhau và có kích thước giới hạn; tham chiếu dữ liệu dùng chung, lớn, hay không giới
|
|
17
|
+
hạn (mảng lớn lên vô hạn gây hại). Lên kế hoạch một field version schema khi hình
|
|
18
|
+
dạng sẽ còn thay đổi.
|
|
19
|
+
|
|
20
|
+
## Khóa và kiểu dữ liệu
|
|
21
|
+
|
|
22
|
+
- Một primary key cho mỗi bảng; theo kiểu ID của dự án (bigint identity, UUID/ULID).
|
|
23
|
+
Khóa UUIDv4 ngẫu nhiên làm phân mảnh index B-tree trên bảng lớn; ID có thứ tự theo
|
|
24
|
+
thời gian tránh được điều đó ở nơi dự án cho phép.
|
|
25
|
+
- Dùng kiểu chính xác: decimal hay số nguyên theo đơn vị nhỏ nhất cho tiền, timestamp
|
|
26
|
+
có múi giờ (hoặc UTC theo quy ước), enum hay check constraint cho các tập đóng, text
|
|
27
|
+
kèm một check độ dài thay vì giới hạn varchar tùy ý.
|
|
28
|
+
- Lưu thời gian theo UTC; chuyển đổi ở biên.
|
|
29
|
+
|
|
30
|
+
## Constraint
|
|
31
|
+
|
|
32
|
+
- Mặc định NOT NULL; chỉ cho nullable khi sự vắng mặt có ý nghĩa.
|
|
33
|
+
- Foreign key cho các quan hệ, với một hành vi ON DELETE được chọn có chủ đích
|
|
34
|
+
(restrict, cascade, set null).
|
|
35
|
+
- Unique constraint cho tính duy nhất nghiệp vụ (email theo từng tenant), không chỉ
|
|
36
|
+
kiểm tra ở tầng app; kiểm tra ở tầng app sẽ bị đua.
|
|
37
|
+
- Check constraint cho các quy tắc giá trị mà engine có thể cưỡng chế.
|
|
38
|
+
- SQLite: foreign key cần bật theo từng kết nối; nhiều thao tác ALTER đòi phải dựng
|
|
39
|
+
lại bảng. MySQL: check constraint chỉ được cưỡng chế từ 8.0.16.
|
|
40
|
+
- Đặt tên constraint và index nhất quán để các migration sau có thể tham chiếu chúng.
|
|
41
|
+
|
|
42
|
+
## Mở rộng rồi thu hẹp
|
|
43
|
+
|
|
44
|
+
Đổi một schema đang sống theo từng bước, mỗi bước tương thích với cả bản app cũ và mới:
|
|
45
|
+
|
|
46
|
+
1. Mở rộng: thêm cột, bảng, hay index mới. Cho nullable hoặc có default an toàn.
|
|
47
|
+
2. Ghi cả hai: deploy code ghi cả hình dạng cũ và mới.
|
|
48
|
+
3. Backfill các dòng hiện có sang hình dạng mới.
|
|
49
|
+
4. Đọc cái mới: chuyển các lượt đọc; kiểm chứng.
|
|
50
|
+
5. Thu hẹp: ngừng ghi hình dạng cũ, rồi xóa nó trong một migration sau.
|
|
51
|
+
|
|
52
|
+
Đổi tên một cột tại chỗ làm vỡ bản đang chạy; hãy dùng thêm-sao chép-chuyển-xóa.
|
|
53
|
+
Thêm NOT NULL cho một cột đang có: thêm một check hoặc validate ở một bước riêng
|
|
54
|
+
sau khi backfill, rồi mới đặt NOT NULL.
|
|
55
|
+
|
|
56
|
+
## Backfill
|
|
57
|
+
|
|
58
|
+
- Tách khỏi migration schema với bảng lớn.
|
|
59
|
+
- Chia lô theo khoảng primary key hoặc keyset (ví dụ 1k-10k dòng mỗi lô), commit theo
|
|
60
|
+
từng lô, nghỉ giữa các lô nếu tải là vấn đề.
|
|
61
|
+
- Idempotent và tiếp tục được: chỉ chọn những dòng vẫn còn cần đổi.
|
|
62
|
+
- Log số lượng tiến độ, không log nội dung dòng.
|
|
63
|
+
- Kiểm chứng: số dòng còn cần đổi bằng không.
|
|
64
|
+
|
|
65
|
+
## Migration đảo được
|
|
66
|
+
|
|
67
|
+
- Cung cấp một bước down khi công cụ hỗ trợ và thay đổi có thể hoàn tác được.
|
|
68
|
+
- Thay đổi phá hủy dữ liệu thì không thể đảo thật sự; kế hoạch rollback là restore
|
|
69
|
+
hoặc một bản sao được giữ lại. Hãy nói thẳng điều đó.
|
|
70
|
+
- Giữ mỗi migration nhỏ và một mục đích; đừng trộn thay đổi schema với thay đổi dữ
|
|
71
|
+
liệu lớn.
|
|
72
|
+
- Đừng bao giờ sửa một migration đã được áp; hãy thêm một migration mới.
|
|
73
|
+
|
|
74
|
+
## Rủi ro locking
|
|
75
|
+
|
|
76
|
+
| Thao tác | Rủi ro | Dạng an toàn hơn |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| Tạo index (PostgreSQL) | chặn các lượt ghi | `CREATE INDEX CONCURRENTLY` ngoài transaction |
|
|
79
|
+
| Tạo index (MySQL InnoDB) | thường là online | xác nhận `ALGORITHM=INPLACE, LOCK=NONE` |
|
|
80
|
+
| Thêm cột với default biến động | ghi lại cả bảng | thêm nullable, backfill, rồi mới đặt default |
|
|
81
|
+
| Đổi kiểu cột | thường là ghi lại | cột mới, backfill, đổi chỗ |
|
|
82
|
+
| Thêm foreign key / check trên bảng lớn | full scan dưới lock | PostgreSQL: `NOT VALID`, rồi `VALIDATE` |
|
|
83
|
+
| Thêm NOT NULL | scan dưới lock | check constraint đã validate trước |
|
|
84
|
+
|
|
85
|
+
- Đặt một lock timeout (ví dụ `SET lock_timeout` trong PostgreSQL) để một migration
|
|
86
|
+
đang chờ sau một transaction dài fail nhanh thay vì chặn toàn bộ lưu lượng.
|
|
87
|
+
- Hành vi khác nhau theo engine và version; hãy xem tài liệu của version đang dùng.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
{
|
|
2
|
+
"label": "Design",
|
|
3
|
+
"description": "Quyết định UI và UX: layout, typography, token, trạng thái tương tác, và review theo các hướng dẫn về khả năng dùng và khả năng tiếp cận.",
|
|
4
|
+
"skills": ["ui-design"],
|
|
5
|
+
"assign": { "lead": ["ui-design"], "peer": ["ui-design"] }
|
|
6
|
+
}
|