tofuu2202/CleanArchitecture-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Te amo
2026-02-26 14:04:18 +07:00
parent 57ac80a666
commit 4b7236493f
92 changed files with 4999 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
docs/GitBranch.md Normal file
View File

@@ -0,0 +1,334 @@
# Huong Dan Dat Ten Git Branch Trong Du An
> **Tham khao:** [Git Branch Naming Conventions - Codiga](https://codiga.io/blog/git-branch-naming-conventions)
---
## Muc Luc
1. [Nguyen Tac Chung](#1-nguyen-tac-chung)
2. [Cau Truc Ten Branch](#2-cau-truc-ten-branch)
3. [Cac Loai Branch (Branch Types)](#3-cac-loai-branch-branch-types)
4. [Bang Mau Ten Branch Theo Chuc Nang](#4-bang-mau-ten-branch-theo-chuc-nang)
5. [Quy Tac Dat Ten (Good Practices)](#5-quy-tac-dat-ten-good-practices)
6. [Mo Hinh Git Flow](#6-mo-hinh-git-flow)
7. [Vi Du Thuc Te Trong Du An](#7-vi-du-thuc-te-trong-du-an)
8. [Checklist Truoc Khi Tao Branch](#8-checklist-truoc-khi-tao-branch)
---
## 1. Nguyen Tac Chung
Theo bai viet tu Codiga, mot quy uoc dat ten branch tot giup:
| # | Loi ich | Mo ta |
|---|---------|-------|
| 1 | **Truy vet tac gia** | Biet ai da tao branch (developer nao) |
| 2 | **Lien ket voi issue tracker** | De dang trace branch voi task/ticket tren JIRA, Trello, GitHub Issues... |
| 3 | **Hieu muc dich branch** | Nhanh chong biet branch la bugfix, feature, hay hotfix |
| 4 | **To chuc workflow** | Giu cho quy trinh lam viec co trat tu va hieu qua |
---
## 2. Cau Truc Ten Branch
### Format chung
```
<type>/<ticket-id>-<short-description>
```
Trong do:
| Thanh phan | Bat buoc | Mo ta | Vi du |
|-----------|----------|-------|-------|
| `type` | Co | Loai branch (feature, bugfix, hotfix...) | `feature` |
| `ticket-id` | Co (neu co) | Ma ticket/issue tu issue tracker | `PROJ-1234` |
| `short-description` | Co | Mo ta ngan 3-6 tu, phan cach bang dau `-` | `add-user-authentication` |
### Vi du day du
```
feature/PROJ-1234-add-user-authentication
bugfix/PROJ-5678-fix-login-redirect
hotfix/PROJ-9012-patch-security-vulnerability
```
### Format mo rong (co ten tac gia)
Neu team co nhieu nguoi lam chung mot ticket, them ten tac gia:
```
<author>/<type>/<ticket-id>-<short-description>
```
Vi du:
```
julien/feature/1234-new-dashboard
david/feature/1234-new-dashboard
```
Dieu nay giup phan biet ro rang code cua tung developer cho cung mot task.
---
## 3. Cac Loai Branch (Branch Types)
### Branch chinh (Long-lived branches)
| Branch | Muc dich | Duoc merge tu | Ghi chu |
|--------|---------|---------------|---------|
| `main` (hoac `master`) | Code production, luon o trang thai stable | `release`, `hotfix` | Khong bao gio commit truc tiep |
| `develop` | Code moi nhat cho phien ban tiep theo | `feature`, `bugfix` | Nhanh tich hop chinh |
| `staging` | Moi truong test truoc khi len production | `develop` | Tuy chon, tuy du an |
### Branch tam thoi (Short-lived branches)
| Prefix | Muc dich | Tao tu | Merge vao | Vi du |
|--------|---------|--------|----------|-------|
| `feature/` | Tinh nang moi | `develop` | `develop` | `feature/PROJ-101-add-login-page` |
| `bugfix/` | Sua loi trong qua trinh phat trien | `develop` | `develop` | `bugfix/PROJ-202-fix-null-reference` |
| `hotfix/` | Sua loi khan cap tren production | `main` | `main` va `develop` | `hotfix/PROJ-303-fix-payment-crash` |
| `release/` | Chuan bi phien ban moi | `develop` | `main` va `develop` | `release/v1.2.0` |
| `chore/` | Cong viec bao tri, refactor, CI/CD | `develop` | `develop` | `chore/update-dependencies` |
| `docs/` | Cap nhat tai lieu | `develop` | `develop` | `docs/update-api-documentation` |
| `test/` | Viet test hoac cai thien test | `develop` | `develop` | `test/add-unit-tests-user-service` |
| `refactor/` | Tai cau truc code, khong thay doi chuc nang | `develop` | `develop` | `refactor/clean-up-user-repository` |
---
## 4. Bang Mau Ten Branch Theo Chuc Nang
### Authentication & Authorization
```
feature/PROJ-101-add-jwt-authentication
feature/PROJ-102-implement-refresh-token
feature/PROJ-103-add-role-based-access
bugfix/PROJ-104-fix-token-expiration
hotfix/PROJ-105-patch-auth-bypass
```
### CRUD Entity
```
feature/PROJ-201-create-product-entity
feature/PROJ-202-add-product-api-endpoints
feature/PROJ-203-implement-product-search
bugfix/PROJ-204-fix-product-update-validation
```
### Infrastructure & DevOps
```
chore/PROJ-301-setup-docker-compose
chore/PROJ-302-configure-ci-cd-pipeline
chore/PROJ-303-add-redis-caching
chore/PROJ-304-setup-logging-serilog
```
### Database & Migration
```
feature/PROJ-401-add-migration-user-table
feature/PROJ-402-seed-initial-data
bugfix/PROJ-403-fix-migration-conflict
```
### Documentation
```
docs/PROJ-501-update-readme
docs/PROJ-502-add-api-swagger-docs
docs/PROJ-503-create-deployment-guide
```
---
## 5. Quy Tac Dat Ten (Good Practices)
### Nen lam
| Quy tac | Chi tiet | Vi du |
|---------|---------|-------|
| **Dung ten mo ta** | Ten branch phai phan anh ro noi dung thay doi | `feature/PROJ-101-add-user-authentication` |
| **Giu ngan gon** | Chi 3-6 tu khoa, phan cach bang dau `-` | `bugfix/PROJ-202-fix-null-ref` |
| **Viet thuong toan bo** | Khong viet hoa | `feature/add-login` |
| **Dung dau `-` phan cach tu** | Khong dung dau cach, underscore, hoac camelCase | `fix-login-redirect` |
| **Bat dau bang type prefix** | Luon co prefix xac dinh loai branch | `feature/`, `bugfix/`, `hotfix/` |
| **Lien ket ticket ID** | Giup trace nguon goc thay doi | `PROJ-1234-...` |
### Khong nen lam
| Quy tac | Vi du sai | Vi du dung |
|---------|----------|-----------|
| **Khong dung ky tu dac biet** | `feature/add@user#auth` | `feature/add-user-auth` |
| **Khong dung dau cach** | `feature/add user auth` | `feature/add-user-auth` |
| **Khong viet hoa** | `Feature/Add-User-Auth` | `feature/add-user-auth` |
| **Khong dat ten chung chung** | `feature/new-stuff` | `feature/PROJ-101-add-payment-gateway` |
| **Khong dat ten qua dai** | `feature/PROJ-101-add-new-user-authentication-with-jwt-and-refresh-token-support-for-all-roles` | `feature/PROJ-101-add-jwt-auth` |
| **Khong dung so thuong** | `feature/123` | `feature/PROJ-123-add-login` |
| **Khong commit truc tiep vao main/develop** | — | Luon tao branch rieng |
---
## 6. Mo Hinh Git Flow
### So do tong quat
```
main (production)
|
|--- hotfix/PROJ-xxx-fix-critical-bug
| |
| v
| (merge vao main VA develop)
|
|--- release/v1.2.0
| |
| v
| (merge vao main VA develop)
|
develop (integration)
|
|--- feature/PROJ-xxx-new-feature
| |
| v
| (merge vao develop qua Pull Request)
|
|--- bugfix/PROJ-xxx-fix-bug
| |
| v
| (merge vao develop qua Pull Request)
|
|--- chore/update-packages
|
v
(merge vao develop qua Pull Request)
```
### Quy trinh lam viec
1. **Tao branch** tu `develop` (hoac `main` cho hotfix)
2. **Commit** thuong xuyen voi message ro rang
3. **Push** branch len remote
4. **Tao Pull Request** (PR) de review code
5. **Review & Approve** boi it nhat 1 thanh vien khac
6. **Merge** vao branch dich (squash merge hoac merge commit)
7. **Xoa branch** sau khi merge thanh cong
### Lenh Git mau
```bash
# Tao branch feature moi tu develop
git checkout develop
git pull origin develop
git checkout -b feature/PROJ-101-add-login-page
# Lam viec va commit
git add .
git commit -m "feat(PROJ-101): add login page UI"
# Push len remote
git push origin feature/PROJ-101-add-login-page
# Sau khi merge PR, xoa branch local
git checkout develop
git pull origin develop
git branch -d feature/PROJ-101-add-login-page
```
---
## 7. Vi Du Thuc Te Trong Du An
### Ap dung cho du an Clean Architecture (MyNewProjectName)
#### Sprint 1: Khoi tao du an
```bash
# Cau hinh co ban
chore/PROJ-001-setup-clean-architecture
chore/PROJ-002-configure-dependency-injection
chore/PROJ-003-setup-ef-core-database
chore/PROJ-004-add-serilog-logging
chore/PROJ-005-setup-docker-compose
```
#### Sprint 2: Authentication
```bash
# Tinh nang xac thuc
feature/PROJ-010-add-user-entity
feature/PROJ-011-implement-jwt-authentication
feature/PROJ-012-add-refresh-token-flow
feature/PROJ-013-implement-role-authorization
bugfix/PROJ-014-fix-token-validation-error
```
#### Sprint 3: CRUD cho SampleEntity
```bash
# Tinh nang CRUD
feature/PROJ-020-add-sample-entity-crud
feature/PROJ-021-add-pagination-support
feature/PROJ-022-implement-search-filter
bugfix/PROJ-023-fix-sample-delete-cascade
```
#### Hotfix khan cap
```bash
# Sua loi tren production
hotfix/PROJ-099-fix-sql-injection-vulnerability
hotfix/PROJ-100-patch-cors-configuration
```
### Quy uoc Commit Message (di kem voi branch)
De dong bo voi quy uoc branch, nen dung [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <description>
```
| Type | Muc dich | Vi du |
|------|---------|-------|
| `feat` | Tinh nang moi | `feat(PROJ-101): add login page` |
| `fix` | Sua loi | `fix(PROJ-202): resolve null reference in UserService` |
| `chore` | Bao tri | `chore: update NuGet packages` |
| `docs` | Tai lieu | `docs: update API documentation` |
| `refactor` | Tai cau truc | `refactor: simplify UserRepository queries` |
| `test` | Them/sua test | `test: add unit tests for AuthService` |
| `style` | Format code | `style: apply editorconfig rules` |
| `ci` | CI/CD | `ci: add GitHub Actions workflow` |
---
## 8. Checklist Truoc Khi Tao Branch
- [ ] Ten branch co bat dau bang type prefix khong? (`feature/`, `bugfix/`, `hotfix/`...)
- [ ] Ten branch co chua ticket/issue ID khong? (`PROJ-1234`)
- [ ] Mo ta co ngan gon va ro rang khong? (3-6 tu)
- [ ] Chi dung chu thuong, so, dau `-` va dau `/`?
- [ ] Khong co ky tu dac biet, dau cach, hoac chu viet hoa?
- [ ] Branch duoc tao tu dung branch nguon? (`develop` hoac `main`)
- [ ] Da pull code moi nhat tu branch nguon truoc khi tao?
---
## Tom Tat Nhanh
```
Format: <type>/<ticket-id>-<short-description>
Vi du: feature/PROJ-101-add-user-authentication
Type: feature | bugfix | hotfix | release | chore | docs | test | refactor
Chu y: - Viet thuong toan bo
- Dung dau `-` phan cach tu
- Giu ngan gon (3-6 tu)
- Khong ky tu dac biet
- Lien ket ticket ID
- Xoa branch sau khi merge
```

468
docs/GitCommit.md Normal file
View File

@@ -0,0 +1,468 @@
# Huong Dan Viet Git Commit Message Trong Du An
> **Tham khao:** [Conventional Commits](https://www.conventionalcommits.org/)
---
## Muc Luc
1. [Nguyen Tac Chung](#1-nguyen-tac-chung)
2. [Cau Truc Commit Message](#2-cau-truc-commit-message)
3. [Cac Loai Type](#3-cac-loai-type)
4. [Scope - Pham Vi Thay Doi](#4-scope---pham-vi-thay-doi)
5. [Quy Tac Viet Description](#5-quy-tac-viet-description)
6. [Commit Message Voi Body Va Footer](#6-commit-message-voi-body-va-footer)
7. [Bang Vi Du Day Du](#7-bang-vi-du-day-du)
8. [Vi Du Thuc Te Trong Du An](#8-vi-du-thuc-te-trong-du-an)
9. [Nhung Loi Thuong Gap](#9-nhung-loi-thuong-gap)
10. [Checklist Truoc Khi Commit](#10-checklist-truoc-khi-commit)
---
## 1. Nguyen Tac Chung
Viet commit message chuan giup:
| # | Loi ich | Mo ta |
|---|---------|-------|
| 1 | **Doc lich su de dang** | Nhin vao git log biet ngay thay doi gi |
| 2 | **Tu dong tao changelog** | Cac tool co the tu dong tao changelog tu commit message |
| 3 | **Lien ket voi issue tracker** | De dang trace commit voi task/ticket |
| 4 | **Review code hieu qua** | Nguoi review hieu nhanh muc dich cua commit |
| 5 | **Tu dong versioning** | Xac dinh phien ban tu dong (semantic versioning) dua tren type |
---
## 2. Cau Truc Commit Message
### Format chung
```
<type>(<scope>): <description>
```
Trong do:
| Thanh phan | Bat buoc | Mo ta | Vi du |
|-----------|----------|-------|-------|
| `type` | Co | Loai thay doi (feat, fix, chore...) | `feat` |
| `scope` | Khong | Pham vi/module bi anh huong | `auth`, `api`, `user` |
| `description` | Co | Mo ta ngan, duoi 50 ky tu, viet hoa dau cau, khong dau cham cuoi | `add Google login` |
### Format day du (voi body va footer)
```
<type>(<scope>): <description>
<body>
<footer>
```
### Vi du nhanh
```
feat(auth): add Google login
fix(api): resolve 404 error
docs(readme): update install guide
chore: update dependencies
```
---
## 3. Cac Loai Type
### Type chinh (thuong dung)
| Type | Muc dich | Anh huong version | Vi du |
|------|---------|-------------------|-------|
| `feat` | Them tinh nang moi | MINOR (1.x.0) | `feat(auth): add Google OAuth` |
| `fix` | Sua loi | PATCH (1.0.x) | `fix(api): resolve 404 error` |
| `docs` | Cap nhat tai lieu | Khong | `docs(readme): update install guide` |
| `style` | Doi format/UI khong anh huong logic | Khong | `style: apply prettier formatting` |
| `refactor` | Tai cau truc code, khong thay doi chuc nang | Khong | `refactor: simplify UserService logic` |
| `perf` | Toi uu hieu nang | PATCH (1.0.x) | `perf: optimize database queries` |
| `test` | Them hoac sua test | Khong | `test: add unit tests for AuthService` |
| `chore` | Thay doi nho, bao tri, CI/CD | Khong | `chore: update dependencies` |
### Type bo sung (it dung hon)
| Type | Muc dich | Vi du |
|------|---------|-------|
| `build` | Thay doi build system hoac dependencies | `build: upgrade to .NET 8` |
| `ci` | Thay doi CI/CD pipeline | `ci: add GitHub Actions workflow` |
| `revert` | Hoan tac commit truoc do | `revert: revert feat(auth): add Google login` |
---
## 4. Scope - Pham Vi Thay Doi
Scope la phan **tuy chon** nam trong dau ngoac `()`, xac dinh module/file/module cu the bi anh huong.
### Danh sach scope khuyen nghi cho du an Clean Architecture
| Scope | Layer/Module | Vi du |
|-------|-------------|-------|
| `domain` | MyNewProjectName.Domain | `feat(domain): add Order entity` |
| `app` | MyNewProjectName.Application | `feat(app): add CreateUserCommand` |
| `infra` | MyNewProjectName.Infrastructure | `feat(infra): configure EF Core DbContext` |
| `api` | MyNewProjectName.WebAPI | `fix(api): resolve CORS issue` |
| `admin` | MyNewProjectName.AdminAPI | `feat(admin): add dashboard endpoint` |
| `contract` | MyNewProjectName.Contracts | `feat(contract): add UserDto` |
| `test` | MyNewProjectName.UnitTest | `test(test): add UserService tests` |
| `auth` | Module xac thuc | `feat(auth): implement JWT refresh token` |
| `cache` | Module caching/Redis | `feat(cache): add Redis caching layer` |
| `db` | Database/Migration | `feat(db): add migration for User table` |
| `docker` | Docker/Container | `chore(docker): update docker-compose` |
| `deps` | Dependencies/NuGet | `chore(deps): update MediatR to v12` |
### Quy tac scope
- Viet thuong toan bo
- Ngan gon, 1-2 tu
- Phai nhat quan trong toan du an
- Co the bo qua neu thay doi anh huong nhieu module
---
## 5. Quy Tac Viet Description
### Nen lam
| Quy tac | Chi tiet | Vi du |
|---------|---------|-------|
| **Viet hoa chu dau** | Chu dau tien cua description viet hoa | `feat: Add login page` |
| **Duoi 50 ky tu** | Giu description ngan gon | `fix: Resolve null reference in UserService` |
| **Dung dong tu menh lenh** | Bat dau bang dong tu (add, fix, update, remove...) | `feat: Add user authentication` |
| **Khong dau cham cuoi** | Khong ket thuc bang dau `.` | `docs: Update README` |
| **Mo ta "lam gi"** | Tap trung vao ket qua, khong phai qua trinh | `fix: Resolve 404 on login redirect` |
### Khong nen lam
| Quy tac | Vi du sai | Vi du dung |
|---------|----------|-----------|
| **Khong viet chung chung** | `fix: Fix bug` | `fix(auth): Resolve token expiration error` |
| **Khong qua dai** | `feat: Add new user authentication with JWT and refresh token and role-based access control` | `feat(auth): Add JWT authentication` |
| **Khong dung qua khu** | `feat: Added login page` | `feat: Add login page` |
| **Khong ghi ten file** | `fix: Fix UserService.cs` | `fix(app): Resolve null ref in user creation` |
| **Khong dung tieng Viet trong type** | `feat: Them trang dang nhap` | `feat: Add login page` |
### Danh sach dong tu khuyen dung
| Dong tu | Khi nao dung | Vi du |
|---------|-------------|-------|
| `add` | Them moi | `feat: Add payment gateway` |
| `remove` | Xoa bo | `refactor: Remove unused imports` |
| `update` | Cap nhat | `docs: Update API documentation` |
| `fix` | Sua loi | `fix: Fix null reference exception` |
| `resolve` | Giai quyet | `fix: Resolve race condition in checkout` |
| `implement` | Hien thuc | `feat: Implement search filter` |
| `refactor` | Tai cau truc | `refactor: Refactor UserRepository` |
| `optimize` | Toi uu | `perf: Optimize query performance` |
| `configure` | Cau hinh | `chore: Configure Serilog logging` |
| `migrate` | Di chuyen/migration | `feat: Migrate user table schema` |
| `replace` | Thay the | `refactor: Replace raw SQL with EF Core` |
| `rename` | Doi ten | `refactor: Rename UserDto to UserResponse` |
| `move` | Di chuyen | `refactor: Move validators to shared folder` |
| `simplify` | Don gian hoa | `refactor: Simplify error handling logic` |
| `extract` | Tach ra | `refactor: Extract email service interface` |
---
## 6. Commit Message Voi Body Va Footer
Khi commit phuc tap, can giai thich them, su dung body va footer:
### Format
```
<type>(<scope>): <description>
<-- dong trong bat buoc
<body>
<-- dong trong bat buoc
<footer>
```
### Vi du 1: Commit co body
```
feat(auth): Add JWT authentication
Implement JWT-based authentication using IdentityServer.
Include access token and refresh token flow.
Configure token expiration to 15 minutes for access token
and 7 days for refresh token.
```
### Vi du 2: Commit co body va footer (lien ket ticket)
```
fix(api): Resolve 500 error on user creation
The API was returning 500 when creating a user with an existing email.
Added proper validation check before inserting into database.
Return 409 Conflict instead of 500 Internal Server Error.
Resolves: PROJ-1234
```
### Vi du 3: Breaking change
```
feat(api)!: Change response format for all endpoints
BREAKING CHANGE: All API responses now follow the new standard format:
{
"success": true,
"data": {},
"message": "",
"errors": []
}
Previous format with flat response body is no longer supported.
Clients must update to handle the new wrapper format.
Resolves: PROJ-5678
```
### Footer keywords
| Keyword | Muc dich | Vi du |
|---------|---------|-------|
| `Resolves:` | Dong issue/ticket | `Resolves: PROJ-1234` |
| `Closes:` | Dong issue tren GitHub | `Closes: #123` |
| `Related:` | Lien quan den issue khac | `Related: PROJ-5678` |
| `BREAKING CHANGE:` | Thay doi khong tuong thich nguoc | `BREAKING CHANGE: API response format changed` |
| `Co-authored-by:` | Dong tac gia | `Co-authored-by: Name <email>` |
| `Reviewed-by:` | Nguoi review | `Reviewed-by: Name <email>` |
---
## 7. Bang Vi Du Day Du
### feat - Them tinh nang moi
```bash
feat(auth): Add Google OAuth login
feat(api): Add pagination support for product list
feat(domain): Add Order entity with value objects
feat(app): Add CreateUserCommand with validation
feat(infra): Add Redis caching for product queries
feat(admin): Add dashboard statistics endpoint
feat(contract): Add OrderResponseDto
```
### fix - Sua loi
```bash
fix(api): Resolve 404 error on login redirect
fix(auth): Fix token expiration calculation
fix(infra): Resolve database connection timeout
fix(app): Fix null reference in GetUserQuery
fix(domain): Fix value object equality comparison
```
### docs - Tai lieu
```bash
docs(readme): Update installation guide
docs(api): Add Swagger annotations for OrderController
docs: Add contributing guidelines
docs: Update environment variables documentation
```
### style - Format code
```bash
style: Apply EditorConfig formatting rules
style(api): Fix indentation in controllers
style: Remove trailing whitespace
```
### refactor - Tai cau truc
```bash
refactor(app): Simplify UserService error handling
refactor(infra): Extract IEmailService interface
refactor: Move validation logic to domain layer
refactor(api): Replace manual mapping with AutoMapper
```
### perf - Toi uu hieu nang
```bash
perf(infra): Optimize database queries with projection
perf(api): Add response compression middleware
perf(cache): Reduce Redis round trips with pipeline
```
### test - Them/sua test
```bash
test(app): Add unit tests for CreateUserCommand
test(domain): Add tests for Order entity validation
test(infra): Add integration tests for UserRepository
test: Increase code coverage to 80%
```
### chore - Bao tri
```bash
chore: Update NuGet packages
chore(deps): Upgrade to .NET 8
chore(docker): Update docker-compose configuration
chore(ci): Add GitHub Actions build workflow
chore: Update .gitignore
```
### build - Build system
```bash
build: Upgrade to .NET 8 SDK
build: Add Directory.Build.props for shared config
build: Configure multi-stage Docker build
```
### ci - CI/CD
```bash
ci: Add GitHub Actions workflow for PR checks
ci: Configure automatic deployment to staging
ci: Add SonarQube code analysis step
```
---
## 8. Vi Du Thuc Te Trong Du An
### Luong lam viec mot feature hoan chinh
Gia su lam task PROJ-101: Them tinh nang dang nhap
```bash
# 1. Tao branch
git checkout -b feature/PROJ-101-add-login
# 2. Them entity va domain logic
git commit -m "feat(domain): Add User entity with email and password"
# 3. Them command/query
git commit -m "feat(app): Add LoginCommand with FluentValidation"
# 4. Them infrastructure
git commit -m "feat(infra): Implement UserRepository with EF Core"
git commit -m "feat(infra): Add password hashing service"
# 5. Them API endpoint
git commit -m "feat(api): Add AuthController with login endpoint"
# 6. Them test
git commit -m "test(app): Add unit tests for LoginCommand handler"
# 7. Cap nhat tai lieu
git commit -m "docs(api): Add Swagger docs for auth endpoints"
# 8. Push va tao PR
git push origin feature/PROJ-101-add-login
```
### Luong sua loi
```bash
# 1. Tao branch
git checkout -b bugfix/PROJ-202-fix-login-error
# 2. Sua loi
git commit -m "fix(auth): Resolve incorrect password validation logic"
# 3. Them test cho truong hop loi
git commit -m "test(auth): Add test for invalid password scenario"
# 4. Push va tao PR
git push origin bugfix/PROJ-202-fix-login-error
```
### Luong hotfix khan cap
```bash
# 1. Tao branch tu main
git checkout main
git checkout -b hotfix/PROJ-303-fix-sql-injection
# 2. Sua loi
git commit -m "fix(infra): Sanitize SQL parameters to prevent injection
The raw SQL query in SearchRepository was concatenating user input
directly into the query string. Replaced with parameterized query
using EF Core's FromSqlInterpolated method.
Resolves: PROJ-303"
# 3. Push va tao PR vao main
git push origin hotfix/PROJ-303-fix-sql-injection
```
---
## 9. Nhung Loi Thuong Gap
| # | Loi sai | Vi du sai | Vi du dung |
|---|--------|----------|-----------|
| 1 | **Message qua chung chung** | `fix: Fix bug` | `fix(auth): Resolve token expiration error` |
| 2 | **Khong co type** | `Add login page` | `feat: Add login page` |
| 3 | **Dung qua khu** | `feat: Added new feature` | `feat: Add new feature` |
| 4 | **Qua nhieu thay doi trong 1 commit** | `feat: Add login, register, forgot password` | Tach thanh 3 commit rieng |
| 5 | **Commit file khong lien quan** | Commit ca file config lan feature | Chi commit file lien quan |
| 6 | **Message tieng Viet** | `feat: Them trang dang nhap` | `feat: Add login page` |
| 7 | **Dau cham cuoi** | `feat: Add login page.` | `feat: Add login page` |
| 8 | **Khong co scope khi can thiet** | `fix: Fix null reference` | `fix(app): Resolve null ref in GetUserQuery` |
| 9 | **Type sai** | `feat: Fix bug` | `fix: Resolve login error` |
| 10 | **Description qua dai** | 100+ ky tu tren 1 dong | Giu duoi 50 ky tu, dung body cho chi tiet |
---
## 10. Checklist Truoc Khi Commit
- [ ] Commit message co dung format `<type>(<scope>): <description>` khong?
- [ ] Type co chinh xac khong? (feat, fix, docs, style, refactor, perf, test, chore)
- [ ] Scope co phan anh dung module bi anh huong khong?
- [ ] Description co duoi 50 ky tu khong?
- [ ] Description co bat dau bang dong tu menh lenh khong? (add, fix, update...)
- [ ] Description co viet hoa chu dau khong?
- [ ] Khong co dau cham cuoi trong description?
- [ ] Moi commit chi chua 1 thay doi logic duy nhat?
- [ ] Commit co lien ket ticket ID khong? (trong scope hoac footer)
- [ ] Neu la breaking change, da danh dau `!` va them `BREAKING CHANGE:` trong footer?
---
## Tom Tat Nhanh
```
Format: <type>(<scope>): <description>
Type: feat | fix | docs | style | refactor | perf | test | chore | build | ci | revert
Scope: domain | app | infra | api | admin | contract | test | auth | cache | db | docker | deps
Vi du:
feat(auth): Add Google OAuth login # scope = "auth" (module authentication)
fix(api): Resolve 404 error # scope = "api" (API endpoints)
docs(readme): Update install guide # scope = "readme" (file/module cu the)
feat: Them tinh nang moi (VD: feat(login): Add Google OAuth).
fix: Sua loi (VD: fix(api): Resolve 404 error).
docs: Cap nhat tai lieu.
style: Doi format/UI khong anh huong logic.
refactor: Tai cau truc code.
perf: Toi uu hieu nang.
chore: Thay doi nho (VD: chore: Update dependencies).
Quy tac:
- Type va scope viet thuong
- Description viet hoa chu dau, duoi 50 ky tu
- Dung dong tu menh lenh (add, fix, update, remove, implement...)
- Khong dau cham cuoi
- 1 commit = 1 thay doi logic
- Lien ket ticket ID khi co the
```

254
docs/Observability-Guide.md Normal file
View File

@@ -0,0 +1,254 @@
# Observability Guide - Serilog & OpenTelemetry
## Tổng quan
Dự án đã được tích hợp **Serilog** (Structured Logging) và **OpenTelemetry** (Distributed Tracing) để hỗ trợ giám sát và debug ứng dụng khi chạy trên production/Docker.
## Serilog - Structured Logging
### Tính năng
- **JSON Format**: Log được ghi dưới dạng JSON, dễ dàng parse và filter
- **Multiple Sinks**: Console, File, Seq, Elasticsearch
- **Enrichment**: Tự động thêm thông tin như Environment, MachineName, ThreadId
- **Rolling Files**: Tự động rotate log files theo ngày/tuần/tháng
### Cấu hình trong appsettings.json
```json
{
"Serilog": {
"MinimumLevel": "Information",
"Override": {
"Microsoft": "Warning",
"Microsoft.AspNetCore": "Warning",
"Microsoft.EntityFrameworkCore": "Warning"
},
"WriteToConsole": true,
"WriteToFile": true,
"FilePath": "logs/log-.txt",
"RollingInterval": "Day",
"RetainedFileCountLimit": 31,
"SeqUrl": "http://localhost:5341",
"ElasticsearchUrl": null
}
}
```
### Sử dụng trong Code
```csharp
using Serilog;
public class MyService
{
private readonly ILogger _logger;
public MyService(ILogger logger)
{
_logger = logger;
}
public void DoSomething()
{
// Structured logging với properties
_logger.Information(
"Processing order {OrderId} for user {UserId}",
orderId,
userId
);
// Log với exception
try
{
// ...
}
catch (Exception ex)
{
_logger.Error(ex, "Failed to process order {OrderId}", orderId);
}
}
}
```
### Log Levels
- **Verbose**: Chi tiết nhất, dùng cho debug
- **Debug**: Thông tin debug
- **Information**: Thông tin thông thường (mặc định)
- **Warning**: Cảnh báo
- **Error**: Lỗi
- **Fatal**: Lỗi nghiêm trọng, ứng dụng có thể crash
### Tích hợp với Seq (Development)
1. Chạy Seq trong Docker:
```bash
docker run -d --name seq -p 5341:80 -e ACCEPT_EULA=Y datalust/seq:latest
```
2. Cập nhật appsettings.json:
```json
{
"Serilog": {
"SeqUrl": "http://localhost:5341"
}
}
```
3. Xem logs tại: http://localhost:5341
### Tích hợp với ELK Stack (Production)
1. Cài đặt Elasticsearch và Kibana
2. Cập nhật appsettings.json với ElasticsearchUrl
3. Xem logs trong Kibana dashboard
## OpenTelemetry - Distributed Tracing
### Tính năng
- **Distributed Tracing**: Theo dõi request qua nhiều services
- **Performance Monitoring**: Đo thời gian thực thi từng operation
- **Automatic Instrumentation**: Tự động instrument ASP.NET Core, HTTP Client, EF Core
- **OTLP Export**: Export traces đến các hệ thống như Jaeger, Zipkin, Grafana
### Cấu hình
OpenTelemetry đã được cấu hình tự động trong `Program.cs`:
```csharp
builder.Services.AddOpenTelemetryTracing("MyNewProjectName.WebAPI");
```
### Instrumentation tự động
- **ASP.NET Core**: Tự động trace HTTP requests/responses
- **HTTP Client**: Trace các HTTP calls đến external APIs
- **Entity Framework Core**: Trace database queries
### Xem Traces
#### Option 1: Console (Development)
Traces được export ra console, có thể thấy trong log output.
#### Option 2: OTLP Collector (Production)
1. Chạy OTLP Collector:
```yaml
# docker-compose.yml
services:
otlp-collector:
image: otel/opentelemetry-collector:latest
ports:
- "4317:4317" # OTLP gRPC receiver
- "4318:4318" # OTLP HTTP receiver
volumes:
- ./otel-collector-config.yaml:/etc/otelcol/config.yaml
```
2. Cấu hình export trong code (nếu cần):
```csharp
.AddOtlpExporter(options =>
{
options.Endpoint = new Uri("http://otlp-collector:4317");
})
```
3. Export đến Jaeger, Zipkin, hoặc Grafana Tempo
### Tích hợp với Jaeger
1. Chạy Jaeger:
```bash
docker run -d --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
jaegertracing/all-in-one:latest
```
2. Xem traces tại: http://localhost:16686
## Best Practices
### 1. Structured Logging
✅ **Tốt**: Sử dụng structured logging với properties
```csharp
_logger.Information("User {UserId} created order {OrderId}", userId, orderId);
```
❌ **Không tốt**: String interpolation
```csharp
_logger.Information($"User {userId} created order {orderId}");
```
### 2. Log Levels
- **Information**: Business events (user login, order created)
- **Warning**: Unexpected situations (retry, fallback)
- **Error**: Exceptions và failures
- **Debug**: Chi tiết kỹ thuật (chỉ trong development)
### 3. Correlation ID
Sử dụng correlation ID để link logs và traces:
```csharp
// Trong middleware
var correlationId = Guid.NewGuid().ToString();
LogContext.PushProperty("CorrelationId", correlationId);
```
### 4. Sensitive Data
❌ **Không log**:
- Passwords
- Credit card numbers
- API keys
- Personal information (PII)
✅ **Log**:
- User IDs (không phải username/email)
- Order IDs
- Request/Response metadata (không có sensitive data)
## Monitoring trong Docker
Khi chạy trong Docker, logs được ghi vào:
- **Console**: `docker logs <container-name>`
- **Files**: `logs/log-*.txt` trong container
- **Seq/ELK**: Nếu đã cấu hình
### Xem logs trong Docker
```bash
# Xem logs real-time
docker logs -f webapi
# Xem logs với timestamp
docker logs -t webapi
# Xem logs của 100 dòng cuối
docker logs --tail 100 webapi
```
## Troubleshooting
### Logs không xuất hiện
1. Kiểm tra `Serilog:WriteToConsole` trong appsettings.json
2. Kiểm tra `Serilog:MinimumLevel` có quá cao không
3. Kiểm tra Docker logs: `docker logs <container-name>`
### Traces không hiển thị
1. Kiểm tra OpenTelemetry đã được add trong Program.cs
2. Kiểm tra OTLP endpoint nếu dùng collector
3. Kiểm tra network connectivity đến collector
### Performance Impact
- Serilog: Minimal impact, async logging
- OpenTelemetry: ~1-2% overhead, có thể disable trong development nếu cần

157
docs/OptionsPattern-Usage.md Normal file
View File

@@ -0,0 +1,157 @@
# Options Pattern - Hướng dẫn sử dụng
## Tổng quan
Options Pattern là cách tiếp cận **Strongly-Typed** để quản lý cấu hình trong .NET, thay vì sử dụng `IConfiguration` trực tiếp với magic strings.
## Lợi ích
1. **Type Safety**: IntelliSense hỗ trợ, tránh lỗi chính tả
2. **Validation**: Validate cấu hình ngay khi khởi động ứng dụng
3. **Separation of Concerns**: Tách biệt Infrastructure (config) khỏi Application logic
4. **Testability**: Dễ dàng mock và test
## Cách sử dụng trong Service
### Ví dụ: Sử dụng JwtOptions trong Service
```csharp
using Microsoft.Extensions.Options;
using MyNewProjectName.Infrastructure.Options;
public class JwtTokenService
{
private readonly JwtOptions _jwtOptions;
// Inject IOptions<JwtOptions> thay vì IConfiguration
public JwtTokenService(IOptions<JwtOptions> jwtOptions)
{
_jwtOptions = jwtOptions.Value;
}
public string GenerateToken()
{
// Sử dụng với IntelliSense hỗ trợ
var secretKey = _jwtOptions.SecretKey;
var issuer = _jwtOptions.Issuer;
var expiration = _jwtOptions.ExpirationInMinutes;
// ... logic tạo token
return token;
}
}
```
### Ví dụ: Sử dụng DatabaseOptions
```csharp
using Microsoft.Extensions.Options;
using MyNewProjectName.Infrastructure.Options;
public class DatabaseService
{
private readonly DatabaseOptions _dbOptions;
public DatabaseService(IOptions<DatabaseOptions> dbOptions)
{
_dbOptions = dbOptions.Value;
}
public string GetConnectionString()
{
return _dbOptions.DefaultConnection;
}
}
```
## Các Options Classes có sẵn
1. **DatabaseOptions** - Cấu hình kết nối database
2. **JwtOptions** - Cấu hình JWT authentication
3. **RedisOptions** - Cấu hình Redis cache
4. **SerilogOptions** - Cấu hình Serilog logging
## Thêm Options Class mới
### Bước 1: Tạo Options Class
```csharp
// MyNewProjectName.Infrastructure/Options/EmailOptions.cs
using System.ComponentModel.DataAnnotations;
namespace MyNewProjectName.Infrastructure.Options;
public class EmailOptions
{
public const string SectionName = "Email";
[Required]
public string SmtpServer { get; set; } = string.Empty;
[Range(1, 65535)]
public int SmtpPort { get; set; } = 587;
[Required]
[EmailAddress]
public string FromAddress { get; set; } = string.Empty;
}
```
### Bước 2: Đăng ký trong DependencyInjection.cs
```csharp
// Trong MyNewProjectName.Infrastructure/DependencyInjection.cs
services.Configure<EmailOptions>(configuration.GetSection(EmailOptions.SectionName));
// Validate (optional)
services.AddOptions<EmailOptions>()
.Bind(configuration.GetSection(EmailOptions.SectionName))
.ValidateDataAnnotations()
.ValidateOnStart();
```
### Bước 3: Thêm vào appsettings.json
```json
{
"Email": {
"SmtpServer": "smtp.gmail.com",
"SmtpPort": 587,
"FromAddress": "noreply@example.com"
}
}
```
### Bước 4: Sử dụng trong Service
```csharp
public class EmailService
{
private readonly EmailOptions _emailOptions;
public EmailService(IOptions<EmailOptions> emailOptions)
{
_emailOptions = emailOptions.Value;
}
}
```
## Validation
Options classes sử dụng Data Annotations để validate:
- `[Required]` - Bắt buộc phải có giá trị
- `[MinLength]` - Độ dài tối thiểu
- `[Range]` - Giá trị trong khoảng
- `[EmailAddress]` - Định dạng email
- Và nhiều attributes khác...
Nếu validation fail, ứng dụng sẽ **không khởi động** và báo lỗi rõ ràng.
## IOptions vs IOptionsSnapshot vs IOptionsMonitor
- **IOptions<T>**: Giá trị được cache, không tự động reload khi config thay đổi
- **IOptionsSnapshot<T>**: Tự động reload khi config thay đổi (scoped)
- **IOptionsMonitor<T>**: Tự động reload và có thể subscribe để nhận thông báo (singleton)
Thông thường, sử dụng **IOptions<T>** là đủ.

391
docs/Redis.md Normal file
View File

@@ -0,0 +1,391 @@
# Hướng Dẫn Đặt Tên Redis Key Trong Dự Án
> **Tham khảo:** [Redis Namespace and Other Keys to Developing with Redis](https://redis.io/blog/5-key-takeaways-for-developing-with-redis/)
---
## Mục Lục
1. [Nguyên Tắc Chung](#1-nguyên-tắc-chung)
2. [Quy Ước Đặt Tên Key (Naming Convention)](#2-quy-ước-đặt-tên-key-naming-convention)
3. [Cấu Trúc Key Theo Namespace](#3-cấu-trúc-key-theo-namespace)
4. [Bảng Mẫu Key Theo Chức Năng](#4-bảng-mẫu-key-theo-chức-năng)
5. [Quy Tắc Về Độ Dài Key](#5-quy-tắc-về-độ-dài-key)
6. [Chọn Đúng Data Structure](#6-chọn-đúng-data-structure)
7. [Quản Lý Key: SCAN thay vì KEYS](#7-quản-lý-key-scan-thay-vì-keys)
8. [Chiến Lược TTL & Expiration](#8-chiến-lược-ttl--expiration)
9. [Cache Invalidation](#9-cache-invalidation)
10. [Ví Dụ Thực Tế Trong Dự Án](#10-ví-dụ-thực-tế-trong-dự-án)
---
## 1. Nguyên Tắc Chung
Theo bài viết từ Redis, có **5 điểm quan trọng** khi phát triển với Redis:
| # | Nguyên tắc | Mô tả |
|---|-----------|-------|
| 1 | **Namespace cho key** | Sử dụng dấu `:` để phân tách các phần của tên key, giúp dễ quản lý và tìm kiếm |
| 2 | **Giữ key ngắn gọn** | Key name cũng chiếm bộ nhớ — key dài 12 ký tự tốn thêm ~15% RAM so với key 6 ký tự (trên 1 triệu key) |
| 3 | **Dùng đúng data structure** | Hash, List, Set, Sorted Set — mỗi loại phù hợp với một use case khác nhau |
| 4 | **Dùng SCAN, không dùng KEYS** | Lệnh `KEYS` có thể block server, `SCAN` an toàn hơn cho production |
| 5 | **Sử dụng Lua Scripts** | Xử lý logic phía server để giảm latency và tối ưu hiệu suất |
---
## 2. Quy Ước Đặt Tên Key (Naming Convention)
### Format chung
```
{project}:{service}:{entity}:{identifier}
```
- **Dấu phân cách:** Luôn dùng dấu hai chấm `:` (colon) — đây là **convention chuẩn** của Redis
- **Chữ thường:** Tất cả các phần của key đều viết **lowercase**
- **Không dấu cách, không ký tự đặc biệt:** Chỉ dùng chữ cái, số, dấu `:` và dấu `-` hoặc `_`
### Đúng
```
myapp:user:profile:12345
myapp:order:detail:ORD-001
myapp:cache:product:list:page:1
```
### Sai
```
MyApp_User_Profile_12345 # Dùng underscore thay vì colon, viết hoa
user profile 12345 # Có dấu cách
MYAPP:USER:PROFILE:12345 # Viết hoa toàn bộ (lãng phí bộ nhớ)
```
---
## 3. Cấu Trúc Key Theo Namespace
Áp dụng cho dự án **Clean Architecture**, cấu trúc key nên phản ánh rõ layer và module:
```
{app}:{layer}:{entity}:{action/scope}:{identifier}
```
### Các prefix theo layer
| Prefix | Ý nghĩa | Ví dụ |
|--------|---------|-------|
| `app:cache` | Cache dữ liệu | `app:cache:product:list` |
| `app:session` | Quản lý session | `app:session:user:abc123` |
| `app:rate` | Rate limiting | `app:rate:api:login:192.168.1.1` |
| `app:lock` | Distributed lock | `app:lock:order:process:ORD-001` |
| `app:queue` | Message queue | `app:queue:email:pending` |
| `app:temp` | Dữ liệu tạm thời | `app:temp:otp:user:12345` |
| `app:pub` | Pub/Sub channels | `app:pub:notifications:user:12345` |
| `app:counter` | Bộ đếm | `app:counter:visit:page:home` |
---
## 4. Bảng Mẫu Key Theo Chức Năng
### Authentication & Authorization
| Key Pattern | Data Type | TTL | Mô tả |
|------------|-----------|-----|--------|
| `app:session:{sessionId}` | Hash | 30 phút | Thông tin session người dùng |
| `app:token:refresh:{userId}` | String | 7 ngày | Refresh token |
| `app:token:blacklist:{jti}` | String | Thời gian còn lại của token | JWT bị thu hồi |
| `app:temp:otp:{userId}` | String | 5 phút | Mã OTP xác thực |
| `app:rate:login:{ip}` | String (counter) | 15 phút | Giới hạn số lần đăng nhập |
### Cache Dữ Liệu (CRUD)
| Key Pattern | Data Type | TTL | Mô tả |
|------------|-----------|-----|--------|
| `app:cache:{entity}:detail:{id}` | Hash/String | 10 phút | Cache chi tiết 1 entity |
| `app:cache:{entity}:list:{hash}` | String (JSON) | 5 phút | Cache danh sách có phân trang/filter |
| `app:cache:{entity}:count` | String | 5 phút | Cache tổng số record |
| `app:cache:{entity}:ids:all` | Set | 10 phút | Tập hợp tất cả ID của entity |
> **`{hash}`** là hash MD5/SHA256 của query parameters (page, filter, sort) để tạo key unique cho mỗi truy vấn khác nhau.
### 🔔 Real-time & Pub/Sub
| Key Pattern | Data Type | TTL | Mô tả |
|------------|-----------|-----|--------|
| `app:pub:notification:{userId}` | Channel | — | Kênh thông báo realtime |
| `app:queue:email:pending` | List | — | Hàng đợi gửi email |
| `app:counter:online:users` | String | — | Đếm user đang online |
### 🔒 Distributed Locking
| Key Pattern | Data Type | TTL | Mô tả |
|------------|-----------|-----|--------|
| `app:lock:{resource}:{id}` | String | 30 giây | Lock tài nguyên để tránh race condition |
---
## 5. Quy Tắc Về Độ Dài Key
Theo bài viết từ Redis:
> *"Storing 1,000,000 keys, each set with a 32-character value, will consume about **96MB** when using 6-character key names, and **111MB** with 12-character names. This overhead of more than **15%** becomes quite significant as your number of keys grows."*
### Hướng dẫn cân bằng
| Quy tắc | Chi tiết |
|---------|---------|
| **Tối đa 50 ký tự** | Giữ tổng chiều dài key không quá 50 ký tự |
| **Viết tắt hợp lý** | `usr` thay vì `user`, `prod` thay vì `product` — nhưng phải có **bảng chú giải** |
| **Không lạm dụng viết tắt** | Key phải đọc được, tránh như `a:b:c:d:1` |
| **Ưu tiên rõ ràng nếu < 10K keys** | Nếu dataset nhỏ, ưu tiên key dễ đọc hơn key ngắn |
### Bảng viết tắt chuẩn (nếu cần tối ưu)
| Viết tắt | Đầy đủ |
|----------|--------|
| `usr` | user |
| `prod` | product |
| `ord` | order |
| `sess` | session |
| `notif` | notification |
| `cfg` | config |
| `inv` | inventory |
| `txn` | transaction |
---
## 6. Chọn Đúng Data Structure
Theo bài viết, việc chọn đúng cấu trúc dữ liệu giúp **tối ưu bộ nhớ và hiệu suất**:
| Data Structure | Khi nào dùng | Ví dụ trong dự án |
|---------------|-------------|-------------------|
| **String** | Giá trị đơn giản, counter, cache JSON | `app:cache:product:detail:123` → JSON string |
| **Hash** | Object có nhiều field, profile user | `app:session:abc123` → `{userId, role, name, exp}` |
| **List** | Queue, danh sách có thứ tự, cho phép trùng | `app:queue:email:pending` → FIFO queue |
| **Set** | Tập hợp unique, kiểm tra membership | `app:cache:user:ids:all` → tập hợp user IDs |
| **Sorted Set** | Leaderboard, ranking, timeline | `app:rank:score:board:game1` → ranking theo điểm |
| **Bitmap** | Track true/false cho lượng lớn, analytics | `app:analytics:daily:login:2026-02-23` → bit per user |
### 💡 Tips quan trọng:
- **Hash thay vì nhiều String**: Nhóm dữ liệu liên quan vào 1 Hash thay vì tạo nhiều key String riêng lẻ → tiết kiệm bộ nhớ đáng kể
- **List thay vì Set**: Nếu không cần kiểm tra uniqueness, List nhanh hơn và tốn ít RAM hơn
- **Tránh Sorted Set nếu không cần ranking**: Sorted Set tốn nhiều bộ nhớ và phức tạp nhất
---
## 7. Quản Lý Key: SCAN thay vì KEYS
### ⚠️ KHÔNG BAO GIỜ dùng `KEYS` trong production!
Lệnh `KEYS *` sẽ:
- **Block toàn bộ Redis server** cho đến khi hoàn thành
- **Tiêu tốn RAM** nguy hiểm
- Gây **downtime** nếu dataset lớn
### Dùng `SCAN` để duyệt key an toàn
```bash
# Cú pháp
SCAN cursor [MATCH pattern] [COUNT count]
# Ví dụ: Tìm tất cả cache key của product
SCAN 0 MATCH "app:cache:product:*" COUNT 100
# Dùng HSCAN cho Hash
HSCAN app:session:abc123 0 MATCH "*"
# Dùng SSCAN cho Set
SSCAN app:cache:user:ids:all 0 COUNT 50
```
### Trong code C# (StackExchange.Redis):
```csharp
// Đúng: Dùng SCAN
var server = redis.GetServer(endpoint);
var keys = server.Keys(pattern: "app:cache:product:*", pageSize: 100);
// Sai: Dùng KEYS (block server)
// var keys = server.Keys(pattern: "app:cache:product:*", pageSize: int.MaxValue);
```
---
## 8. Chiến Lược TTL & Expiration
| Loại dữ liệu | TTL khuyến nghị | Lý do |
|--------------|----------------|-------|
| **Cache API response** | 5 – 15 phút | Đảm bảo data tương đối fresh |
| **Session** | 30 phút – 2 giờ | Theo session timeout của app |
| **OTP / Verification** | 3 – 10 phút | Bảo mật |
| **Refresh Token** | 7 – 30 ngày | Theo chính sách auth |
| **Rate Limit Counter** | 1 – 60 phút | Theo window rate limit |
| **Distributed Lock** | 10 – 60 giây | Tránh deadlock |
| **Analytics / Counter** | Không expire hoặc 24h | Tùy yêu cầu business |
### ⚡ Luôn đặt TTL cho mọi cache key!
```csharp
// Luôn set expiration khi SET
await db.StringSetAsync("app:cache:product:detail:123", jsonData, TimeSpan.FromMinutes(10));
// Hoặc set TTL riêng
await db.KeyExpireAsync("app:cache:product:detail:123", TimeSpan.FromMinutes(10));
```
> ⚠️ **Cảnh báo:** Key không có TTL sẽ tồn tại mãi mãi → nguy cơ memory leak!
---
## 9. Cache Invalidation
Khi dữ liệu thay đổi trong database chính (SQL, MongoDB...), cần **xóa cache Redis tương ứng**:
### Pattern: Tag-based Invalidation
```
# Khi tạo cache, thêm key vào một Set quản lý
SADD app:tags:product app:cache:product:detail:123
SADD app:tags:product app:cache:product:list:abc
SADD app:tags:product app:cache:product:count
# Khi invalidate, duyệt Set và xóa tất cả
SMEMBERS app:tags:product → lấy tất cả key liên quan
DEL app:cache:product:detail:123 app:cache:product:list:abc ...
DEL app:tags:product
```
### Trong code C#:
```csharp
public async Task InvalidateCacheByTagAsync(string tag)
{
var db = _redis.GetDatabase();
var tagKey = $"app:tags:{tag}";
// Lấy tất cả cache key thuộc tag này
var members = await db.SetMembersAsync(tagKey);
if (members.Length > 0)
{
// Xóa tất cả cache key
var keys = members.Select(m => (RedisKey)m.ToString()).ToArray();
await db.KeyDeleteAsync(keys);
}
// Xóa luôn tag set
await db.KeyDeleteAsync(tagKey);
}
```
---
## 10. Ví Dụ Thực Tế Trong Dự Án
Áp dụng quy ước cho dự án **MyNewProjectName** (Clean Architecture):
### Entity: `SampleEntity`
```
# Cache chi tiết
app:cache:sample:detail:{id}
# Cache danh sách (hash = MD5 của query params)
app:cache:sample:list:{queryHash}
# Cache count
app:cache:sample:count
# Tag để invalidation
app:tags:sample → Set chứa tất cả key cache liên quan
# Lock khi cập nhật
app:lock:sample:update:{id}
```
### Authentication Flow
```
# Session sau khi login
app:session:{sessionId} → Hash { userId, role, loginAt, ip }
# Refresh token
app:token:refresh:{userId} → "eyJhbGciOi..."
# OTP xác thực email
app:temp:otp:{userId} → "123456" (TTL: 5 phút)
# Blacklist JWT đã revoke
app:token:blacklist:{jti} → "1" (TTL: thời gian còn lại của token)
# Rate limit login
app:rate:login:{ip} → counter (TTL: 15 phút, max: 5 lần)
```
### Constant class trong C#
```csharp
/// <summary>
/// Định nghĩa tất cả Redis key patterns sử dụng trong dự án.
/// Sử dụng dấu ':' làm namespace separator theo convention chuẩn Redis.
/// </summary>
public static class RedisKeyPatterns
{
private const string Prefix = "app";
// ── Cache ──────────────────────────────────
public static string CacheDetail(string entity, string id)
=> $"{Prefix}:cache:{entity}:detail:{id}";
public static string CacheList(string entity, string queryHash)
=> $"{Prefix}:cache:{entity}:list:{queryHash}";
public static string CacheCount(string entity)
=> $"{Prefix}:cache:{entity}:count";
// ── Tags (cho cache invalidation) ──────────
public static string Tag(string entity)
=> $"{Prefix}:tags:{entity}";
// ── Session ────────────────────────────────
public static string Session(string sessionId)
=> $"{Prefix}:session:{sessionId}";
// ── Token ──────────────────────────────────
public static string RefreshToken(string userId)
=> $"{Prefix}:token:refresh:{userId}";
public static string BlacklistToken(string jti)
=> $"{Prefix}:token:blacklist:{jti}";
// ── Temporary ──────────────────────────────
public static string Otp(string userId)
=> $"{Prefix}:temp:otp:{userId}";
// ── Rate Limiting ──────────────────────────
public static string RateLimit(string action, string identifier)
=> $"{Prefix}:rate:{action}:{identifier}";
// ── Distributed Lock ───────────────────────
public static string Lock(string resource, string id)
=> $"{Prefix}:lock:{resource}:{id}";
}
```
---
## 📋 Checklist Trước Khi Tạo Key Mới
- [ ] Key có sử dụng namespace với dấu `:` không?
- [ ] Key có phản ánh đúng layer/module không?
- [ ] Key có ngắn gọn nhưng vẫn dễ hiểu không? (< 50 ký tự)
- [ ] Đã chọn đúng data structure (String/Hash/List/Set/Sorted Set)?
- [ ] Đã đặt TTL phù hợp cho key?
- [ ] Đã có chiến lược invalidation khi data thay đổi?
- [ ] Đã thêm key pattern vào class `RedisKeyPatterns`?
- [ ] Không dùng `KEYS` command trong code production?
---
> **💡 Ghi nhớ:** *"Luôn namespace key bằng dấu `:`, giữ key ngắn gọn, chọn đúng data structure, dùng SCAN thay vì KEYS, và luôn đặt TTL!"*

BIN
docs/image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.7 MiB