354 lines
8.8 KiB
Markdown
354 lines
8.8 KiB
Markdown
# Pattern [Tên Pattern]
|
|
|
|
> **Mô tả**: Mô tả ngắn gọn về khi nào và tại sao sử dụng pattern này
|
|
|
|
## Tổng quan Pattern
|
|
|
|
```mermaid
|
|
graph LR
|
|
Input[Đầu vào/Yêu cầu] --> Process[Xử lý Pattern]
|
|
Process --> Output[Đầu ra/Kết quả]
|
|
|
|
subgraph Pattern["Triển khai Pattern"]
|
|
Process --> Step1[Bước 1]
|
|
Step1 --> Step2[Bước 2]
|
|
Step2 --> Step3[Bước 3]
|
|
end
|
|
|
|
style Input fill:#e1f5ff
|
|
style Output fill:#d4edda
|
|
style Pattern fill:#f0e1ff
|
|
```
|
|
|
|
## Khi nào sử dụng
|
|
|
|
Sử dụng pattern này khi:
|
|
- Tình huống 1: Mô tả khi pattern này có lợi
|
|
- Tình huống 2: Trường hợp sử dụng khác
|
|
- Tình huống 3: Bối cảnh bổ sung
|
|
|
|
**NÊN sử dụng pattern này cho**:
|
|
- ✅ Trường hợp 1
|
|
- ✅ Trường hợp 2
|
|
|
|
**KHÔNG NÊN sử dụng pattern này cho**:
|
|
- ❌ Anti-pattern 1
|
|
- ❌ Anti-pattern 2
|
|
|
|
## Khái niệm Cốt lõi
|
|
|
|
### Nguyên tắc Chính
|
|
|
|
1. **Nguyên tắc 1**: Mô tả nguyên tắc cốt lõi đầu tiên
|
|
2. **Nguyên tắc 2**: Mô tả nguyên tắc cốt lõi thứ hai
|
|
3. **Nguyên tắc 3**: Mô tả nguyên tắc cốt lõi thứ ba
|
|
|
|
## Triển khai
|
|
|
|
### Triển khai Cơ bản
|
|
|
|
Giải thích từng bước về cách triển khai pattern này.
|
|
|
|
```typescript
|
|
// Ví dụ triển khai cơ bản
|
|
|
|
/**
|
|
* Class triển khai pattern
|
|
*/
|
|
export class ExamplePattern {
|
|
/**
|
|
* Constructor với các dependencies
|
|
*/
|
|
constructor(
|
|
private dependency1: Dependency1,
|
|
private dependency2: Dependency2
|
|
) {}
|
|
|
|
/**
|
|
* Phương thức cốt lõi triển khai pattern
|
|
*
|
|
* @param input - Dữ liệu đầu vào
|
|
* @returns Kết quả đã xử lý
|
|
*/
|
|
async execute(input: InputType): Promise<OutputType> {
|
|
// Bước 1: Validate đầu vào
|
|
this.validateInput(input);
|
|
|
|
// Bước 2: Xử lý
|
|
const processed = await this.process(input);
|
|
|
|
// Bước 3: Trả về kết quả
|
|
return this.formatOutput(processed);
|
|
}
|
|
|
|
private validateInput(input: InputType): void {
|
|
// Logic validation
|
|
if (!input) {
|
|
throw new Error('Đầu vào là bắt buộc');
|
|
}
|
|
}
|
|
|
|
private async process(input: InputType): Promise<ProcessedType> {
|
|
// Logic nghiệp vụ cốt lõi
|
|
return await this.dependency1.transform(input);
|
|
}
|
|
|
|
private formatOutput(processed: ProcessedType): OutputType {
|
|
// Định dạng cho đầu ra
|
|
return {
|
|
success: true,
|
|
data: processed,
|
|
};
|
|
}
|
|
}
|
|
```
|
|
|
|
### Triển khai Nâng cao
|
|
|
|
Triển khai phức tạp hơn với các tính năng bổ sung.
|
|
|
|
```typescript
|
|
// Triển khai nâng cao với caching và xử lý lỗi
|
|
|
|
export class AdvancedExamplePattern extends ExamplePattern {
|
|
constructor(
|
|
dependency1: Dependency1,
|
|
dependency2: Dependency2,
|
|
private cache: CacheService,
|
|
private logger: Logger
|
|
) {
|
|
super(dependency1, dependency2);
|
|
}
|
|
|
|
async execute(input: InputType): Promise<OutputType> {
|
|
// Thử cache trước
|
|
const cacheKey = this.getCacheKey(input);
|
|
const cached = await this.cache.get<OutputType>(cacheKey);
|
|
|
|
if (cached) {
|
|
this.logger.info('Cache hit', { key: cacheKey });
|
|
return cached;
|
|
}
|
|
|
|
try {
|
|
// Thực thi logic pattern
|
|
const result = await super.execute(input);
|
|
|
|
// Cache kết quả
|
|
await this.cache.set(cacheKey, result, 300); // 5 phút
|
|
|
|
return result;
|
|
} catch (error) {
|
|
// Xử lý lỗi
|
|
this.logger.error('Thực thi pattern thất bại', { error, input });
|
|
throw new PatternExecutionError('Thực thi thất bại', { cause: error });
|
|
}
|
|
}
|
|
|
|
private getCacheKey(input: InputType): string {
|
|
return `pattern:example:${JSON.stringify(input)}`;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Sơ đồ Pattern
|
|
|
|
### Cấu trúc Class
|
|
|
|
```mermaid
|
|
classDiagram
|
|
class ExamplePattern {
|
|
-dependency1: Dependency1
|
|
-dependency2: Dependency2
|
|
+execute(input: InputType): OutputType
|
|
-validateInput(input: InputType): void
|
|
-process(input: InputType): ProcessedType
|
|
-formatOutput(processed: ProcessedType): OutputType
|
|
}
|
|
|
|
class AdvancedExamplePattern {
|
|
-cache: CacheService
|
|
-logger: Logger
|
|
+execute(input: InputType): OutputType
|
|
-getCacheKey(input: InputType): string
|
|
}
|
|
|
|
ExamplePattern <|-- AdvancedExamplePattern
|
|
```
|
|
|
|
### Luồng Tuần tự
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Khách hàng
|
|
participant Pattern as ExamplePattern
|
|
participant Dep1 as Dependency1
|
|
participant Cache as CacheService
|
|
|
|
Client->>Pattern: execute(input)
|
|
Pattern->>Cache: get(cacheKey)
|
|
Cache-->>Pattern: null (cache miss)
|
|
Pattern->>Pattern: validateInput(input)
|
|
Pattern->>Dep1: transform(input)
|
|
Dep1-->>Pattern: processed
|
|
Pattern->>Pattern: formatOutput(processed)
|
|
Pattern->>Cache: set(cacheKey, result, ttl)
|
|
Cache-->>Pattern: void
|
|
Pattern-->>Client: result
|
|
```
|
|
|
|
## Ví dụ Sử dụng
|
|
|
|
### Ví dụ 1: Sử dụng Cơ bản
|
|
|
|
Tình huống sử dụng cơ bản với giải thích.
|
|
|
|
```typescript
|
|
// Thiết lập
|
|
const dependency1 = new Dependency1();
|
|
const dependency2 = new Dependency2();
|
|
const pattern = new ExamplePattern(dependency1, dependency2);
|
|
|
|
// Thực thi pattern
|
|
const input: InputType = {
|
|
id: '123',
|
|
data: 'example',
|
|
};
|
|
|
|
const result = await pattern.execute(input);
|
|
|
|
console.log(result);
|
|
// Kết quả: { success: true, data: { ... } }
|
|
```
|
|
|
|
### Ví dụ 2: Sử dụng Nâng cao
|
|
|
|
Sử dụng nâng cao với caching được bật.
|
|
|
|
```typescript
|
|
// Thiết lập với các dependencies bổ sung
|
|
const cache = new CacheService();
|
|
const logger = new Logger();
|
|
const pattern = new AdvancedExamplePattern(
|
|
dependency1,
|
|
dependency2,
|
|
cache,
|
|
logger
|
|
);
|
|
|
|
// Lần gọi đầu tiên (cache miss)
|
|
const result1 = await pattern.execute(input);
|
|
|
|
// Lần gọi thứ hai (cache hit)
|
|
const result2 = await pattern.execute(input); // Trả về kết quả cached
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Thực hành Được đề xuất
|
|
|
|
1. **Nguyên tắc 1**: Mô tả best practice với lý do
|
|
2. **Nguyên tắc 2**: Hướng dẫn quan trọng khác
|
|
3. **Nguyên tắc 3**: Khuyến nghị bổ sung
|
|
|
|
**Cấu hình**:
|
|
```typescript
|
|
const config = {
|
|
timeout: 5000,
|
|
retries: 3,
|
|
cacheTime: 300, // 5 phút
|
|
};
|
|
```
|
|
|
|
## Lỗi Thường gặp
|
|
|
|
### Lỗi 1: [Mô tả]
|
|
|
|
```typescript
|
|
// ❌ KHÔNG TỐT: Triển khai không chính xác
|
|
const result = await pattern.execute(null); // Sẽ throw error
|
|
```
|
|
|
|
```typescript
|
|
// ✅ TỐT: Triển khai chính xác
|
|
if (input) {
|
|
const result = await pattern.execute(input);
|
|
}
|
|
```
|
|
|
|
**Tại sao**: Giải thích tại sao cách tiếp cận đầu tiên là không tốt và cách thứ hai là tốt.
|
|
|
|
## Cân nhắc Hiệu suất
|
|
|
|
**Mô tả**: Đặc điểm hiệu suất và mẹo tối ưu hóa.
|
|
|
|
| Khía cạnh | Tác động | Giảm thiểu |
|
|
|-----------|----------|------------|
|
|
| Sử dụng RAM | Trung bình | Sử dụng caching có chiến lược |
|
|
| Sử dụng CPU | Thấp | N/A |
|
|
| Thao tác I/O | Cao | Triển khai connection pooling |
|
|
|
|
## Kiểm thử
|
|
|
|
```typescript
|
|
// Unit test cho pattern
|
|
|
|
describe('ExamplePattern', () => {
|
|
let pattern: ExamplePattern;
|
|
let mockDep1: jest.Mocked<Dependency1>;
|
|
|
|
beforeEach(() => {
|
|
mockDep1 = {
|
|
transform: jest.fn(),
|
|
} as any;
|
|
|
|
pattern = new ExamplePattern(mockDep1, {} as any);
|
|
});
|
|
|
|
it('nên thực thi thành công', async () => {
|
|
// Chuẩn bị
|
|
const input = { id: '123', data: 'test' };
|
|
const expectedProcessed = { transformed: true };
|
|
mockDep1.transform.mockResolvedValue(expectedProcessed);
|
|
|
|
// Thực thi
|
|
const result = await pattern.execute(input);
|
|
|
|
// Kiểm tra
|
|
expect(result.success).toBe(true);
|
|
expect(result.data).toEqual(expectedProcessed);
|
|
expect(mockDep1.transform).toHaveBeenCalledWith(input);
|
|
});
|
|
|
|
it('nên throw error cho đầu vào không hợp lệ', async () => {
|
|
// Mong đợi lỗi cho đầu vào null
|
|
await expect(pattern.execute(null as any))
|
|
.rejects
|
|
.toThrow('Đầu vào là bắt buộc');
|
|
});
|
|
});
|
|
```
|
|
|
|
## Patterns Liên quan
|
|
|
|
Các patterns khác bổ sung hoặc liên quan đến pattern này.
|
|
|
|
- [Pattern Liên quan 1](./related-pattern-1.md) - Cách nó liên quan
|
|
- [Pattern Liên quan 2](./related-pattern-2.md) - So sánh
|
|
- [Pattern Thay thế](./alternative-pattern.md) - Khi nào sử dụng thay thế
|
|
|
|
## Tài nguyên Bổ sung
|
|
|
|
### Tài liệu Liên quan
|
|
|
|
- [Hướng dẫn Thiết kế API](../api-design.md) - Pattern này khớp với thiết kế API như thế nào
|
|
- [Xử lý Lỗi](../error-handling-patterns.md) - Xử lý lỗi cho pattern này
|
|
- [Hướng dẫn Kiểm thử](../testing-patterns.md) - Chiến lược kiểm thử
|
|
|
|
---
|
|
|
|
**Cập nhật lần cuối**: YYYY-MM-DD
|
|
**Độ phức tạp**: Beginner/Intermediate/Advanced
|
|
**Danh mục**: [Tên Danh mục]
|
|
**Tác giả**: Tên của bạn
|