📚 Student Management Web API (.NET 8)

Giao diện Swagger UI của Student Management API

📋 Giới thiệu

Đây là một ứng dụng Web API được xây dựng bằng .NET 8, tuân thủ các nguyên tắc RESTful API để quản lý thông tin sinh viên và lớp học. Dự án này tập trung vào việc thực hiện các chức năng CRUD (Create, Read, Update, Delete) cơ bản, quản lý quan hệ giữa sinh viên và lớp học, đồng thời áp dụng các kỹ thuật như phân tách lớp Service, xử lý lỗi bằng try-catch và sử dụng Collection List để lưu trữ dữ liệu trong bộ nhớ (in-memory).

📑 Mục lục

• 📚 Student Management Web API (.NET 8)
  • 📋 Giới thiệu
  • 📑 Mục lục
  • ✨ Tính năng
  • 🛠️ Công nghệ sử dụng
  • 🏗️ Cấu trúc dự án
  • 🚀 Thiết lập và Chạy dự án
  • 📊 Mô hình dữ liệu
  • 🔌 API Endpoints
    • 👨‍🎓 Quản lý Sinh viên
    • 🏫 Quản lý Lớp học
    • 🔗 Quản lý Quan hệ Sinh viên - Lớp học
  • 📝 Cấu trúc DTOs
  • ⚠️ Xử lý lỗi
  • 💾 Lưu trữ dữ liệu
  • ✅ Validation

✨ Tính năng

Dự án cung cấp các chức năng chính sau:

Quản lý Sinh viên:

• ➕ Thêm mới một sinh viên.
• 🔄 Cập nhật thông tin sinh viên theo ID.
• 🔍 Lấy thông tin chi tiết sinh viên theo ID.
• 📋 Lấy danh sách tất cả sinh viên.
• ❌ Xóa sinh viên theo ID.

Quản lý Lớp học:

• ➕ Thêm mới một lớp học.
• 🔄 Cập nhật thông tin lớp học theo ID.
• 🔍 Lấy thông tin chi tiết lớp học theo ID.
• 📋 Lấy danh sách tất cả lớp học.
• ❌ Xóa lớp học theo ID (đồng thời xóa các bản ghi liên kết sinh viên với lớp học đó).

Quản lý Quan hệ Sinh viên - Lớp học:

• ➕ Thêm nhiều sinh viên vào một lớp học cùng lúc.
• 🔍 Lấy danh sách sinh viên thuộc một lớp học cụ thể theo ID lớp học.

🛠️ Công nghệ sử dụng

.NET 8

ASP.NET Core Web API

C#

Swagger

🏗️ Cấu trúc dự án

Dự án được tổ chức theo kiến trúc phân lớp cơ bản:

StudentManagementAPI/
├── Controllers/             # Tiếp nhận HTTP requests
│   ├── ClassesController.cs
│   └── StudentsController.cs
├── Services/                # Xử lý logic nghiệp vụ
│   ├── Interfaces/
│   │   ├── IClassService.cs
│   │   └── IStudentService.cs
│   └── Implementations/
│       ├── ClassService.cs
│       └── StudentService.cs
├── Models/                  # Các đối tượng thực thể
│   ├── Class.cs
│   ├── Student.cs
│   └── StudentClass.cs
├── DTOs/                    # Data Transfer Objects
│   ├── ClassDtos.cs
│   └── StudentDtos.cs
└── Data/                    # Lớp lưu trữ dữ liệu
    └── InMemoryDataStore.cs

• Controllers: Tiếp nhận HTTP request, gọi đến các Service tương ứng và trả về HTTP response.
• Services: Chứa logic nghiệp vụ (business logic), xử lý dữ liệu và tương tác với lớp lưu trữ dữ liệu.
• DTOs (Data Transfer Objects): Định nghĩa cấu trúc dữ liệu cho việc trao đổi giữa client và server (request/response bodies), bao gồm cả các quy tắc validation.
• Models: Định nghĩa các đối tượng thực thể cốt lõi (Student, Class, StudentClass).
• Data: Chứa lớp quản lý dữ liệu trong bộ nhớ (InMemoryDataStore).

🚀 Thiết lập và Chạy dự án

Các bước thiết lập:

1. Clone repository:

   git clone https://github.com/shuncoder/Student-Manager-WebApi.git
   cd StudentManagementAPI

2. Restore dependencies:

   dotnet restore

3. Build dự án:

   dotnet build

4. Chạy dự án:

   dotnet run

API sẽ khởi chạy và lắng nghe tại địa chỉ được cấu hình (thường là http://localhost:5xxx và https://localhost:7xxx). Bạn có thể xem chi tiết địa chỉ trong output của console.

Lưu ý: Dự án tích hợp Swagger UI để cung cấp tài liệu API trực quan và cho phép người dùng dễ dàng tương tác, thử nghiệm các endpoints trực tiếp từ trình duyệt. Truy cập /swagger sau khi khởi động API.

📊 Mô hình dữ liệu

Student	Class	StudentClass
Id (Guid): Mã định danh duy nhất. Name (string): Tên sinh viên (tối đa 50 ký tự). StudentCode (string): Mã số sinh viên. DateOfBirth (DateOnly): Ngày tháng năm sinh.	Id (Guid): Mã định danh duy nhất. Name (string): Tên lớp (tối đa 50 ký tự). ClassCode (string): Mã lớp (tối thiểu 5 ký tự). MaxStudents (int): Số sinh viên tối đa (lớn hơn 0).	Id (Guid): Mã định danh quan hệ. StudentId (Guid): Khóa ngoại tới Student. ClassId (Guid): Khóa ngoại tới Class.

🔌 API Endpoints

Dưới đây là danh sách các endpoints được cung cấp bởi API:

Lưu ý: Thay thế {id}, {classId}, {studentId} bằng giá trị GUID thực tế

👨‍🎓 Quản lý Sinh viên

Method	URL	Mô tả	Request Body	Response (Success)	Response (Error)
POST	/api/students	Thêm sinh viên mới	CreateStudentDto	201 Created + StudentDto	400 Bad Request
PUT	/api/students/{id}	Cập nhật sinh viên theo ID	UpdateStudentDto	200 OK + StudentDto	400 Bad Request, 404 Not Found
GET	/api/students/{id}	Lấy chi tiết sinh viên theo ID		200 OK + StudentDto	404 Not Found
GET	/api/students	Lấy danh sách sinh viên		200 OK + List
DELETE	/api/students/{id}	Xóa sinh viên theo ID		204 No Content	404 Not Found

🏫 Quản lý Lớp học

Method	URL	Mô tả	Request Body	Response (Success)	Response (Error)
POST	/api/classes	Thêm lớp học mới	CreateClassDto	201 Created + ClassDto	400 Bad Request
PUT	/api/classes/{id}	Cập nhật lớp học theo ID	UpdateClassDto	200 OK + ClassDto	400 Bad Request, 404 Not Found
GET	/api/classes/{id}	Lấy chi tiết lớp học theo ID		200 OK + ClassDto	404 Not Found
GET	/api/classes	Lấy danh sách lớp học		200 OK + List
DELETE	/api/classes/{id}	Xóa lớp học theo ID (kèm SV)		204 No Content	404 Not Found

🔗 Quản lý Quan hệ Sinh viên - Lớp học

Method	URL	Mô tả	Request Body	Response (Success)	Response (Error)
POST	/api/classes/add-students	Thêm nhiều sinh viên vào lớp	AddStudentsToClassDto	200 OK	400 Bad Request, 404 Not Found
GET	/api/classes/{id}/students	Lấy danh sách sinh viên trong lớp theo ID		200 OK + List	404 Not Found

📝 Cấu trúc DTOs

🧑 CreateStudentDto & UpdateStudentDto

{ 
  "name": "Nguyễn Văn A", 
  "studentCode": "SV001", 
  "dateOfBirth": "2003-05-10" 
}

🏫 CreateClassDto & UpdateClassDto

// CreateClassDto
{ 
  "name": "Lập Trình C#", 
  "classCode": "CSHARP01", 
  "maxStudents": 30 
}

// UpdateClassDto
{ 
  "name": "Lập Trình C# Nâng Cao", 
  "classCode": "CSHARP01", 
  "maxStudents": 40 
}

🔗 AddStudentsToClassDto

{ 
  "classId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", 
  "studentIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "5da85f64-5717-4562-b3fc-2c963f66afa7"
  ] 
}

⚠️ Xử lý lỗi

• ✅ Các action trong Controller sử dụng khối try-catch để bắt các ngoại lệ (exceptions) có thể xảy ra trong tầng Service.
• 🔍 Các lỗi phổ biến như không tìm thấy tài nguyên (Not Found), dữ liệu không hợp lệ (Bad Request) sẽ được trả về với mã trạng thái HTTP tương ứng (404, 400).
• 🔄 Các lỗi không mong muốn khác sẽ được log lại và trả về mã 500 Internal Server Error.

💾 Lưu trữ dữ liệu

• 📋 Dự án này sử dụng System.Collections.Generic.List<T> để lưu trữ dữ liệu sinh viên, lớp học và quan hệ giữa chúng trong bộ nhớ (in-memory) thông qua class InMemoryDataStore.
• 🔧 Dữ liệu mẫu được khởi tạo trong constructor của InMemoryDataStore để demo.
• ⚠️ Lưu ý: Dữ liệu sẽ bị mất khi ứng dụng khởi động lại. Đây chỉ là giải pháp tạm thời cho mục đích demo hoặc phát triển ban đầu. Để lưu trữ bền vững, cần tích hợp với cơ sở dữ liệu (SQL Server, PostgreSQL, MongoDB,...).

✅ Validation

Các ràng buộc dữ liệu (constraints) được định nghĩa trong các lớp DTO sử dụng Data Annotations của .NET:

Annotation	Mô tả	Ví dụ
[Required]	Bắt buộc phải có giá trị	[Required(ErrorMessage = "Tên sinh viên là bắt buộc.")]
[MaxLength]	Độ dài tối đa	[MaxLength(50, ErrorMessage = "Tên sinh viên không được vượt quá 50 ký tự.")]
[MinLength]	Độ dài tối thiểu	[MinLength(5, ErrorMessage = "Mã lớp phải có ít nhất 5 ký tự.")]
[Range]	Giới hạn phạm vi giá trị	[Range(1, int.MaxValue, ErrorMessage = "Số sinh viên tối đa phải lớn hơn 0.")]

ASP.NET Core tự động kiểm tra các validation này khi model binding diễn ra. Nếu dữ liệu không hợp lệ, Controller sẽ trả về lỗi 400 Bad Request kèm theo chi tiết lỗi bằng tiếng Việt.