mirror of
https://github.com/opelly27/WinStudentGoalTracker.git
synced 2026-05-20 15:47:35 +00:00
555 lines
17 KiB
Markdown
555 lines
17 KiB
Markdown
# .NET API Project Design Document
|
|
|
|
A reference architecture for building ASP.NET Core Web APIs with Dapper, JWT authentication, and a co-located data access layer.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
All code lives in a single project. The data access layer is organized as a namespace within the same assembly rather than a separate project.
|
|
|
|
```
|
|
MyApi/
|
|
├── MyApi.sln
|
|
├── MyApi.csproj
|
|
├── Program.cs
|
|
├── appsettings.json
|
|
├── appsettings.Development.json
|
|
├── Dockerfile
|
|
├── Configuration/
|
|
│ └── (Options classes for external services)
|
|
├── DataAccess/
|
|
│ ├── DatabaseManager.cs
|
|
│ ├── Models/
|
|
│ │ ├── DatabaseObjects/
|
|
│ │ └── DataTransferObjects/
|
|
│ └── Repositories/
|
|
└── src/
|
|
├── BaseClasses/
|
|
│ └── BaseController.cs
|
|
├── Controllers/
|
|
├── Middleware/
|
|
├── Models/
|
|
│ └── ResponseTypes/
|
|
└── Services/
|
|
```
|
|
|
|
---
|
|
|
|
## Layer Responsibilities
|
|
|
|
### Controllers (`src/Controllers/`)
|
|
|
|
Controllers handle HTTP concerns only: request validation, claims extraction, and response shaping. They delegate all business logic to services and all data access to repositories.
|
|
|
|
```csharp
|
|
[ApiController]
|
|
[Route("api/[controller]")]
|
|
public class ExampleController : BaseController
|
|
{
|
|
private readonly ExampleRepository _exampleRepository = new();
|
|
|
|
[HttpGet("{id}")]
|
|
[Authorize]
|
|
public async Task<ActionResult<ResponseResult<ExampleResponse>>> GetById(Guid id)
|
|
{
|
|
var (userId, error) = GetUserIdFromClaims();
|
|
if (error != null) return error;
|
|
|
|
var entity = await _exampleRepository.GetByIdAsync(id);
|
|
if (entity == null) return NotFound();
|
|
|
|
return Ok(new ResponseResult<ExampleResponse>
|
|
{
|
|
Success = true,
|
|
Data = MapToResponse(entity)
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
**Conventions:**
|
|
- Use `[ApiController]` and `[Route("api/[controller]")]` on every controller
|
|
- Inherit from `BaseController` for claims extraction helpers
|
|
- Return `ActionResult<ResponseResult<T>>` for consistent response envelopes
|
|
- Apply `[Authorize]` or `[Authorize(Roles = "...")]` per-endpoint
|
|
- Use `[ProducesResponseType]` attributes for OpenAPI documentation
|
|
|
|
### Base Controller (`src/BaseClasses/BaseController.cs`)
|
|
|
|
Provides protected helper methods that extract and validate JWT claims, reducing boilerplate across controllers.
|
|
|
|
```csharp
|
|
public class BaseController : ControllerBase
|
|
{
|
|
protected (Guid userId, ActionResult? error) GetUserIdFromClaims() { ... }
|
|
protected (string email, List<string> roles, ActionResult? error) GetUserDetailsFromClaims() { ... }
|
|
protected bool HasRole(string role) { ... }
|
|
protected bool HasAnyRole(params string[] roles) { ... }
|
|
}
|
|
```
|
|
|
|
Add additional claim extraction helpers as needed for your domain (e.g., tenant ID, organization ID).
|
|
|
|
These methods return tuples with an optional error `ActionResult`, enabling early-return patterns in controller actions.
|
|
|
|
### Services (`src/Services/`)
|
|
|
|
Services encapsulate business logic that spans multiple repositories or involves non-trivial orchestration. Services are either static classes (for stateless logic) or singletons instantiated directly where needed.
|
|
|
|
**When to use a service vs. calling a repository directly from a controller:**
|
|
- **Direct repository call:** Simple CRUD with no cross-cutting logic
|
|
- **Service:** Multi-step operations, external API calls, or any logic spanning multiple repositories
|
|
|
|
**Static service pattern** (preferred for stateless logic):
|
|
|
|
```csharp
|
|
public static class MyService
|
|
{
|
|
public static async Task<Result> DoSomethingAsync(Guid entityId)
|
|
{
|
|
var repo = new ExampleRepository();
|
|
// orchestration logic
|
|
}
|
|
}
|
|
```
|
|
|
|
**Singleton instance pattern** (when the service needs initialization or holds config):
|
|
|
|
```csharp
|
|
public class MyService
|
|
{
|
|
public static MyService Instance { get; private set; } = null!;
|
|
|
|
public static void Initialize(string apiKey, string baseUrl)
|
|
{
|
|
Instance = new MyService { _apiKey = apiKey, _baseUrl = baseUrl };
|
|
}
|
|
|
|
private string _apiKey;
|
|
private string _baseUrl;
|
|
|
|
public async Task<Result> DoSomethingAsync() { ... }
|
|
}
|
|
|
|
// In Program.cs
|
|
MyService.Initialize(
|
|
builder.Configuration["MyService:ApiKey"]!,
|
|
builder.Configuration["MyService:BaseUrl"]!);
|
|
```
|
|
|
|
### Repositories (`DataAccess/Repositories/`)
|
|
|
|
Each repository maps to a single domain entity and serves as a thin C# wrapper around stored procedures. Repositories create their own database connections per call and are responsible for calling stored procedures and assembling the results into typed objects.
|
|
|
|
**All query logic lives in stored procedures in the database — repositories contain no inline SQL.**
|
|
|
|
```csharp
|
|
public class ExampleRepository
|
|
{
|
|
private IDbConnection Connection =>
|
|
new MySqlConnection(DatabaseManager.ConnectionString);
|
|
|
|
public async Task<dbExample?> GetByIdAsync(Guid id)
|
|
{
|
|
using var db = Connection;
|
|
return await db.QuerySingleOrDefaultAsync<dbExample>(
|
|
"sp_Example_GetById",
|
|
new { Id = id },
|
|
commandType: CommandType.StoredProcedure);
|
|
}
|
|
|
|
public async Task<IEnumerable<dbExample>> GetByOwnerAsync(Guid ownerId)
|
|
{
|
|
using var db = Connection;
|
|
return await db.QueryAsync<dbExample>(
|
|
"sp_Example_GetByOwner",
|
|
new { OwnerId = ownerId },
|
|
commandType: CommandType.StoredProcedure);
|
|
}
|
|
|
|
public async Task<bool> InsertAsync(dbExample entity)
|
|
{
|
|
using var db = Connection;
|
|
var rows = await db.ExecuteAsync(
|
|
"sp_Example_Insert",
|
|
new { entity.Id, entity.Name, entity.CreatedAt },
|
|
commandType: CommandType.StoredProcedure);
|
|
return rows > 0;
|
|
}
|
|
|
|
/// For stored procedures that return multiple result sets,
|
|
/// use QueryMultipleAsync to assemble a composite object.
|
|
public async Task<ExampleWithDetails?> GetWithDetailsAsync(Guid id)
|
|
{
|
|
using var db = Connection;
|
|
using var multi = await db.QueryMultipleAsync(
|
|
"sp_Example_GetWithDetails",
|
|
new { Id = id },
|
|
commandType: CommandType.StoredProcedure);
|
|
|
|
var example = await multi.ReadSingleOrDefaultAsync<dbExample>();
|
|
if (example == null) return null;
|
|
|
|
var tags = (await multi.ReadAsync<dbTag>()).ToList();
|
|
var history = (await multi.ReadAsync<dbHistoryEntry>()).ToList();
|
|
|
|
return new ExampleWithDetails
|
|
{
|
|
Example = example,
|
|
Tags = tags,
|
|
History = history
|
|
};
|
|
}
|
|
}
|
|
```
|
|
|
|
**Conventions:**
|
|
- One repository per domain entity
|
|
- All methods are `async Task<T>`
|
|
- Use `using var db = Connection;` to ensure connection disposal
|
|
- **All data access goes through stored procedures** — no inline SQL in repositories
|
|
- Always pass `commandType: CommandType.StoredProcedure` to Dapper calls
|
|
- Use `QueryMultipleAsync` when a stored procedure returns multiple result sets, and assemble the results into composite objects
|
|
- Return `db`-prefixed model types from database operations
|
|
- Stored procedure naming convention: `sp_{Entity}_{Action}` (e.g., `sp_Example_GetById`, `sp_User_Insert`)
|
|
|
|
### Database Objects (`DataAccess/Models/DatabaseObjects/`)
|
|
|
|
Plain C# classes that map directly to database tables. Use the `db` prefix to distinguish them from response DTOs.
|
|
|
|
```csharp
|
|
public class dbExample
|
|
{
|
|
public required Guid Id { get; set; }
|
|
public required string Name { get; set; }
|
|
public string? Description { get; set; }
|
|
public bool Deleted { get; set; }
|
|
public DateTime CreatedAt { get; set; }
|
|
public DateTime UpdatedAt { get; set; }
|
|
}
|
|
```
|
|
|
|
**Conventions:**
|
|
- `db` prefix on all database object class names
|
|
- Use `required` for non-nullable columns
|
|
- Use nullable types (`string?`, `Guid?`) for optional columns
|
|
- Include `CreatedAt` and `UpdatedAt` timestamps on all entities
|
|
- Use `bool Deleted` for soft-delete support where needed
|
|
|
|
### Data Transfer Objects (`DataAccess/Models/DataTransferObjects/`)
|
|
|
|
DTOs define the shape of data entering repositories from controllers. They are distinct from both database objects and response types.
|
|
|
|
```csharp
|
|
public class CreateExampleDTO
|
|
{
|
|
public required string Name { get; set; }
|
|
public string? Description { get; set; }
|
|
}
|
|
|
|
public class UpdateExampleDTO
|
|
{
|
|
public Guid Id { get; set; }
|
|
public string? Name { get; set; }
|
|
public string? Description { get; set; }
|
|
}
|
|
```
|
|
|
|
### Response Types (`src/Models/ResponseTypes/`)
|
|
|
|
Response types define the shape of data returned to API consumers. Use a standard envelope.
|
|
|
|
```csharp
|
|
public class ResponseResult<T>
|
|
{
|
|
public bool Success { get; set; }
|
|
public string? Message { get; set; }
|
|
public T? Data { get; set; }
|
|
}
|
|
```
|
|
|
|
Domain-specific response classes map from database objects, excluding internal fields and reshaping data for client consumption.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Configuration Helper
|
|
|
|
A static helper class provides access to `IConfiguration` from anywhere in the application, without dependency injection.
|
|
|
|
```csharp
|
|
// Configuration/ConfigHelper.cs
|
|
public static class ConfigHelper
|
|
{
|
|
public static IConfiguration Configuration { get; set; } = null!;
|
|
}
|
|
|
|
// Program.cs (before any services are used)
|
|
ConfigHelper.Configuration = builder.Configuration;
|
|
```
|
|
|
|
Configuration values are read directly where needed:
|
|
|
|
```csharp
|
|
var apiKey = ConfigHelper.Configuration["MyService:ApiKey"];
|
|
var baseUrl = ConfigHelper.Configuration["MyService:BaseUrl"];
|
|
```
|
|
|
|
For services that need config at initialization, pass values explicitly during setup in `Program.cs` rather than reading config inside the service.
|
|
|
|
### DatabaseManager
|
|
|
|
A static class that provides the connection string to all repositories. Configures Dapper's snake_case-to-PascalCase column mapping.
|
|
|
|
```csharp
|
|
public static class DatabaseManager
|
|
{
|
|
private static IConfiguration? _configuration;
|
|
|
|
private static IConfiguration Configuration
|
|
{
|
|
get
|
|
{
|
|
if (_configuration == null)
|
|
{
|
|
Dapper.DefaultTypeMap.MatchNamesWithUnderscores = true;
|
|
_configuration = new ConfigurationBuilder()
|
|
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
|
|
.AddEnvironmentVariables()
|
|
.Build();
|
|
}
|
|
return _configuration;
|
|
}
|
|
}
|
|
|
|
public static string ConnectionString =>
|
|
Configuration.GetConnectionString("DefaultConnection")
|
|
?? throw new MissingFieldException("DefaultConnection not configured");
|
|
}
|
|
```
|
|
|
|
### appsettings.json Structure
|
|
|
|
```json
|
|
{
|
|
"Jwt": {
|
|
"Key": "<base64-encoded-signing-key>",
|
|
"Issuer": "MyApi"
|
|
},
|
|
"ConnectionStrings": {
|
|
"DefaultConnection": "Server=...;Database=...;Uid=...;Pwd=...;Pooling=true;Max Pool Size=200;Min Pool Size=5;"
|
|
},
|
|
"MyService": { ... },
|
|
"Logging": {
|
|
"LogLevel": {
|
|
"Default": "Information"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication & Authorization
|
|
|
|
### JWT Configuration
|
|
|
|
```csharp
|
|
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
|
|
.AddJwtBearer(options =>
|
|
{
|
|
options.TokenValidationParameters = new TokenValidationParameters
|
|
{
|
|
ValidateIssuer = true,
|
|
ValidateAudience = false,
|
|
ValidateLifetime = true,
|
|
ValidateIssuerSigningKey = true,
|
|
ValidIssuer = builder.Configuration["Jwt:Issuer"],
|
|
IssuerSigningKey = new SymmetricSecurityKey(
|
|
Convert.FromBase64String(builder.Configuration["Jwt:Key"]!)),
|
|
ClockSkew = TimeSpan.Zero
|
|
};
|
|
});
|
|
```
|
|
|
|
### Token Service
|
|
|
|
A static helper class that generates JWTs with custom claims. Reads JWT config via `ConfigHelper`. Add whatever domain-specific claims your application requires (e.g., user ID, tenant/org ID, email).
|
|
|
|
```csharp
|
|
public static class TokenService
|
|
{
|
|
public static string GenerateToken(Guid userId, string email, List<string> roles)
|
|
{
|
|
var claims = new List<Claim>
|
|
{
|
|
new("user_id", userId.ToString()),
|
|
new(ClaimTypes.Email, email)
|
|
};
|
|
// Add domain-specific claims as needed
|
|
claims.AddRange(roles.Select(r => new Claim(ClaimTypes.Role, r)));
|
|
|
|
var key = new SymmetricSecurityKey(
|
|
Convert.FromBase64String(ConfigHelper.Configuration["Jwt:Key"]!));
|
|
var token = new JwtSecurityToken(
|
|
issuer: ConfigHelper.Configuration["Jwt:Issuer"],
|
|
expires: DateTime.UtcNow.AddMinutes(15),
|
|
claims: claims,
|
|
signingCredentials: new SigningCredentials(key, SecurityAlgorithms.HmacSha256));
|
|
|
|
return new JwtSecurityTokenHandler().WriteToken(token);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Role-Based Authorization
|
|
|
|
Define roles as string constants in a static class and apply them via attributes.
|
|
|
|
```csharp
|
|
public static class UserRoles
|
|
{
|
|
public const string Admin = "Admin";
|
|
public const string User = "User";
|
|
// Add application-specific roles as needed
|
|
}
|
|
|
|
// Usage on endpoints
|
|
[Authorize(Roles = UserRoles.Admin)]
|
|
[HttpDelete("{id}")]
|
|
public async Task<ActionResult> Delete(Guid id) { ... }
|
|
```
|
|
|
|
---
|
|
|
|
## Middleware Pipeline
|
|
|
|
Configure middleware in `Program.cs` in the following order:
|
|
|
|
```csharp
|
|
var app = builder.Build();
|
|
|
|
app.UseMiddleware<GlobalExceptionHandler>(); // 1. Catch unhandled exceptions
|
|
app.UseMiddleware<RequestLoggingMiddleware>(); // 2. Log all requests/responses
|
|
app.UseCors(); // 3. CORS policy
|
|
app.UseHttpsRedirection(); // 4. HTTPS enforcement
|
|
app.UseAuthentication(); // 5. JWT validation
|
|
app.UseAuthorization(); // 6. Role/policy checks
|
|
app.MapControllers(); // 7. Route to controllers
|
|
```
|
|
|
|
### Request Logging Middleware
|
|
|
|
Captures request/response details to the database for observability:
|
|
- HTTP method, path, query string, status code
|
|
- Request and response bodies (excluding multipart/form-data)
|
|
- User ID extracted from JWT claims
|
|
- Processing time in milliseconds
|
|
- Request trace ID for correlation
|
|
|
|
---
|
|
|
|
## Program.cs Template
|
|
|
|
```csharp
|
|
var builder = WebApplication.CreateBuilder(args);
|
|
|
|
// --- Static configuration (must come first) ---
|
|
ConfigHelper.Configuration = builder.Configuration;
|
|
|
|
// --- Kestrel configuration ---
|
|
builder.WebHost.ConfigureKestrel(options =>
|
|
{
|
|
options.Limits.MaxRequestBodySize = 50 * 1024 * 1024; // 50 MB
|
|
});
|
|
|
|
// --- Authentication ---
|
|
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
|
|
.AddJwtBearer(options => { /* see JWT Configuration above */ });
|
|
builder.Services.AddAuthorization();
|
|
|
|
// --- Controllers ---
|
|
builder.Services.AddControllers();
|
|
|
|
// --- Background services (if needed) ---
|
|
// builder.Services.AddHostedService<MyBackgroundWorker>();
|
|
|
|
// --- CORS ---
|
|
builder.Services.AddCors(options =>
|
|
{
|
|
options.AddDefaultPolicy(policy =>
|
|
{
|
|
policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();
|
|
});
|
|
});
|
|
|
|
// --- Forwarded headers (for reverse proxy) ---
|
|
builder.Services.Configure<ForwardedHeadersOptions>(options =>
|
|
{
|
|
options.ForwardedHeaders =
|
|
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
|
|
options.KnownNetworks.Clear();
|
|
options.KnownProxies.Clear();
|
|
});
|
|
|
|
// --- Initialize singleton services ---
|
|
MyService.Initialize(
|
|
builder.Configuration["MyService:ApiKey"]!,
|
|
builder.Configuration["MyService:BaseUrl"]!);
|
|
|
|
var app = builder.Build();
|
|
|
|
app.UseForwardedHeaders();
|
|
app.UseMiddleware<GlobalExceptionHandler>();
|
|
app.UseMiddleware<RequestLoggingMiddleware>();
|
|
app.UseCors();
|
|
app.UseHttpsRedirection();
|
|
app.UseAuthentication();
|
|
app.UseAuthorization();
|
|
app.MapControllers();
|
|
|
|
app.Run();
|
|
```
|
|
|
|
---
|
|
|
|
## Instantiation Patterns
|
|
|
|
| Component | Pattern | Example |
|
|
|---|---|---|
|
|
| Repositories | `new` in controllers | `private readonly ExampleRepository _repo = new();` |
|
|
| Stateless services | Static class | `TokenService.GenerateToken(...)` |
|
|
| Stateful services | Singleton with `Initialize` | `MyService.Instance.DoSomething()` |
|
|
| Configuration | Static helper | `ConfigHelper.Configuration["Key"]` |
|
|
| Background workers | Hosted Service (only DI used) | `builder.Services.AddHostedService<MyWorker>()` |
|
|
|
|
The only use of the DI container is for framework-level concerns that require it: authentication, authorization, CORS, hosted background services, and forwarded headers. All application-level code uses static classes or direct instantiation.
|
|
|
|
---
|
|
|
|
## Key Technology Choices
|
|
|
|
| Concern | Technology |
|
|
|---|---|
|
|
| Framework | ASP.NET Core 9.0 |
|
|
| ORM | Dapper (micro-ORM, stored procedure calls only) |
|
|
| Database | MySQL via MySql.Data |
|
|
| Authentication | JWT Bearer tokens |
|
|
|
|
---
|
|
|
|
## Patterns & Conventions Summary
|
|
|
|
1. **Repository pattern** with one repository per domain entity
|
|
2. **Stored procedures exclusively** — all query logic lives in the database, repositories are thin wrappers
|
|
3. **Snake_case DB columns** mapped automatically to PascalCase C# properties
|
|
4. **Standard response envelope** (`ResponseResult<T>`) on all endpoints
|
|
5. **Claims-based authorization** with role constants and BaseController helpers
|
|
6. **Static configuration helper** for accessing `appsettings.json` anywhere
|
|
7. **No dependency injection** for application code — static classes and direct instantiation only
|
|
8. **Async/await throughout** — no synchronous database calls
|
|
9. **Soft deletes** via `Deleted` boolean flag where needed
|
|
10. **Audit timestamps** (`CreatedAt`, `UpdatedAt`) on all entities
|