antv
125 lines
5.9 KiB
Markdown
125 lines
5.9 KiB
Markdown
# Tài liệu cấu hình và sử dụng System Error Pages
|
|
|
|
Tài liệu này hướng dẫn chi tiết cách hoạt động, các trường hợp sử dụng, cách kích hoạt (trigger) và kiểm thử các trang lỗi hệ thống trong dự án **thankcard-system**.
|
|
|
|
---
|
|
|
|
## 1. Danh sách các trang lỗi & Tình huống sử dụng
|
|
|
|
| Status Code | Tên lỗi | Tình huống sử dụng | Key Localization (`errors.php`) |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **401** | Unauthorized | Người dùng chưa đăng nhập nhưng cố truy cập tài nguyên yêu cầu xác thực. | `errors.401_title` / `errors.401_message` |
|
|
| **403** | Forbidden | Người dùng đã đăng nhập nhưng không có quyền hạn thực hiện hành động này (ví dụ: User thường cố truy cập chức năng Admin). | `errors.403_title` / `errors.403_message` |
|
|
| **404** | Not Found | Đường dẫn (URL) không tồn tại, hoặc khi tìm dữ liệu bằng Model binding/Query không thấy mà muốn trả về lỗi. | `errors.404_title` / `errors.404_message` |
|
|
| **419** | Session Expired | Phiên làm việc hết hạn hoặc token CSRF không hợp lệ/hết hạn khi gửi Form (POST/PUT/DELETE). | `errors.419_title` / `errors.419_message` |
|
|
| **429** | Too Many Requests | Người dùng/IP gửi quá nhiều yêu cầu trong thời gian ngắn (vượt giới hạn Rate Limit của Middleware). | `errors.429_title` / `errors.429_message` |
|
|
| **500** | Internal Error | Lỗi xảy ra từ phía máy chủ hoặc do code PHP bị lỗi crash, kết nối cơ sở dữ liệu thất bại... | `errors.500_title` / `errors.500_message` |
|
|
| **503** | Service Unavailable | Hệ thống đang được bảo trì khi chạy lệnh `php artisan down`. | `errors.503_title` / `errors.503_message` |
|
|
|
|
---
|
|
|
|
## 2. Cách kích hoạt (Trigger) trong Laravel
|
|
|
|
Trong Laravel, bạn có thể trigger các trang lỗi này bằng nhiều cách khác nhau tùy thuộc vào ngữ cảnh.
|
|
|
|
### 2.1. Sử dụng hàm `abort()` (Khuyên dùng trong Controller/Service)
|
|
Hàm `abort()` sẽ ném ra một `HttpException` và Laravel sẽ tự động bắt lấy để render trang lỗi tương ứng nằm trong `resources/views/errors/{status}.blade.php`.
|
|
|
|
```php
|
|
// Ví dụ kiểm tra quyền trong Controller
|
|
if ($user->role !== 'admin') {
|
|
abort(403, 'Bạn không có quyền quản trị viên.');
|
|
}
|
|
|
|
// Ví dụ không tìm thấy tài nguyên
|
|
$card = Card::find($id);
|
|
if (!$card) {
|
|
abort(404, 'Không tìm thấy thẻ cảm ơn.');
|
|
}
|
|
```
|
|
|
|
### 2.2. Sử dụng lệnh bảo trì hệ thống (Maintenance Mode)
|
|
Kích hoạt lỗi **503** bằng cách đưa ứng dụng vào trạng thái bảo trì:
|
|
```bash
|
|
php artisan down
|
|
```
|
|
Để tắt chế độ bảo trì và đưa hệ thống hoạt động bình thường:
|
|
```bash
|
|
php artisan up
|
|
```
|
|
|
|
### 2.3. Sử dụng Middleware (Rate Limiting cho lỗi 429)
|
|
Laravel tích hợp sẵn middleware `throttle`. Bạn có thể áp dụng nó trong file Routes (`routes/web.php` hoặc `routes/api.php`):
|
|
```php
|
|
Route::middleware('throttle:60,1')->group(function () {
|
|
Route::get('/send-card', [UserController::class, 'send']);
|
|
});
|
|
```
|
|
*(Nếu một IP gọi quá 60 lần/phút, Laravel sẽ tự động ném ra lỗi 429 và render trang 429)*
|
|
|
|
---
|
|
|
|
## 3. Ví dụ triển khai thực tế
|
|
|
|
### Trong Controller/Service:
|
|
```php
|
|
namespace App\Http\Controllers;
|
|
|
|
use App\Services\User\Contracts\UserServiceInterface;
|
|
use Illuminate\Http\Request;
|
|
|
|
class UserController extends Controller
|
|
{
|
|
protected $userService;
|
|
|
|
public function __construct(UserServiceInterface $userService)
|
|
{
|
|
$this->userService = $userService;
|
|
}
|
|
|
|
public function show($id)
|
|
{
|
|
$user = $this->userService->findUserById($id);
|
|
|
|
if (!$user) {
|
|
// Tự động render view errors/404.blade.php
|
|
abort(404);
|
|
}
|
|
|
|
return view('user.profile', compact('user'));
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Checklist kiểm thử các trang lỗi
|
|
|
|
Để chắc chắn các trang lỗi hoạt động chính xác và hiển thị đẹp mắt, hãy tiến hành kiểm thử theo checklist sau:
|
|
|
|
- [ ] **Test 401 Unauthorized:**
|
|
- Tạm thời gỡ bỏ middleware auth ở một route và ném `abort(401)`.
|
|
- Kiểm tra xem có hiển thị nút **"Đi đến trang Đăng Nhập"** hay không.
|
|
- [ ] **Test 403 Forbidden:**
|
|
- Đăng nhập tài khoản User thường, sau đó truy cập một route dành riêng cho Admin hoặc ném `abort(403)`.
|
|
- Kiểm tra xem nút **"Quay lại Trang Chủ"** có hoạt động chính xác không.
|
|
- [ ] **Test 404 Not Found:**
|
|
- Truy cập một đường dẫn ngẫu nhiên không khai báo trong route (ví dụ: `http://localhost:8888/path-does-not-exist`).
|
|
- Kiểm tra giao diện và nút **"Quay lại Trang Chủ"**.
|
|
- [ ] **Test 419 Session Expired:**
|
|
- Mở một trang có form POST, xóa trường `_token` ẩn (CSRF) trong thẻ `<form>` bằng Inspect Element của trình duyệt rồi bấm Submit.
|
|
- Hoặc ném `abort(419)`.
|
|
- Kiểm tra xem có hiển thị nút **"Tải lại trang"** hay không.
|
|
- [ ] **Test 429 Too Many Requests:**
|
|
- Cấu hình tạm thời middleware `throttle:3,1` trên route chính và bấm F5 liên tục 4 lần.
|
|
- Hoặc gọi `abort(429)`.
|
|
- Kiểm tra thông báo lỗi.
|
|
- [ ] **Test 500 Internal Server Error:**
|
|
- Thêm một dòng code bị lỗi cú pháp cố ý trong Controller (ví dụ: gọi hàm không tồn tại `$this->nonExistentMethod()`).
|
|
- Hoặc gọi `abort(500)`.
|
|
- Đảm bảo giao diện trang 500 hiển thị thân thiện, không làm lộ stack trace kỹ thuật của code PHP.
|
|
- [ ] **Test 503 Maintenance:**
|
|
- Chạy lệnh `php artisan down` trong container Docker.
|
|
- Tải lại trình duyệt để xem trang bảo trì 503 và nút **"Thử lại"**.
|
|
- Chạy `php artisan up` để đưa website trở lại bình thường.
|