An Opinionated, Maintainable API Code Architecture for ASP.NET Core

Transcript

1. An Opinionated and Maintainable API Code Architecture For ASP.NET Core Spencer Schneidenbach
3. Setting the Stage • “We need a new React backend” • “We need a new REST API”
4. ASP.NET Core
5. “Zero to Make Magic Happen”
6. SCAFFOLDING
8. Introducing the Employee public class Employee { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string SocialSecurityNumber { get; set; } }
9. The Employee Object • Is part of payroll software • Contains sensitive data (social security number)
12. That’s better public class Employee { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
13. The Employee Object • Is part of payroll software • Contains sensitive data (social security number) rodné číslo
14. You, the Developer • Loves dotnet command line/Visual Studio tooling • Loves to get stuff done
15. ASP.NET Core + Entity Framework Core
16. File -> New Project
17. Startup.cs
28. “Scaffolding is AMAZING!”
31. Scaffolding is a LIE
32. Controller is a one man army • Route the request • Validate the request • Run service to execute request • Return data
33. ZERO Separation of Concerns
34. Controller should ONLY • Route the request • Return data
35. Entity is ALSO the request
36. public class Employee { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
39. Let’s Break it Up
40. CQRS Command Query Responsibility Segregation
41. Bottom Line - move: • Validation • Execution • Request
42. Why? • Separation of concerns • Easier testing • An easy pattern to follow
43. First, the request
44. public class Employee { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
45. Problem? • Entity being used for requests • Model/model validation are not separate
46. Rule 1: Separate Entity from Model So let’s refactor!
47. public class Employee { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
48. Business Rule Can create employee with RodneCislo but not update it later using this API
49. Create (POST) public class CreateEmployeeRequest { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
50. Update (PUT) public class UpdateEmployeeRequest { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } }
51. Delete (DELETE) public class DeleteEmployeeRequest { public int Id { get; set; } }
52. Validation public class CreateEmployeeRequest { public int Id { get; set; } [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } public DateTime DateOfBirth { get; set; } public DateTime DateOfHire { get; set; } public string RodneCislo { get; set; } }
53. Clunky to validate
55. Rule 2: Separate Validation from Model Introducing FluentValidation
56. public class CreateEmployeeRequest { [Required] public string FirstName { get; set; } [Required] public string LastName { get; set; } }
57. Let’s isolate the validation functionality
58. public class EmployeeCreateValidator : AbstractValidator<EmployeeCreateRequest> { public EmployeeValidator() { RuleFor(e => e.FirstName).NotEmpty() .WithMessage("First name is required.") RuleFor(e => e.LastName).NotEmpty() .WithMessage("Last name is required.") } }
59. public class EmployeeCreateValidator : AbstractValidator<EmployeeCreateRequest> { public EmployeeValidator() { RuleFor(e => e.FirstName).NotEmpty() .WithMessage("First name is required.") RuleFor(e => e.LastName).NotEmpty() .WithMessage("Last name is required.") } } public class EmployeeCreateRequest { public string FirstName { get; set; } public string LastName { get; set; } }
60. [Test] public void EmployeeNameIsRequired() { var request = new EmployeeCreateRequest(); //no props var validator = new EmployeeCreateValidator(); var result = validator.Validate(request); var firstNameMissing = result.Any(r => r.PropertyName == "FirstName"); var lastNameMissing = result.Any(r => r.PropertyName == "LastName"); Assert.That(firstNameMissing, Is.EqualTo(true)); Assert.That(lastNameMissing, Is.EqualTo(true)); } Test Independently
61. Dependencies public class EmployeeDeleteValidator : AbstractValidator<EmployeeDeleteRequest> { public ApplicationDbContext Context { get; } public EmployeeValidator(ApplicationDbContext context) { Context = context; RuleFor(e => e.Id).Must(ExistInDatabase) .WithMessage("ID does not exist.") } public void ExistInDatabase(EmployeeDeleteRequest request) { return Context.Employee.Find(request.Id) != null; } }
62. What We’ve Accomplished • Separated requests from the entity • Separated validation from entity and requests
64. Rule 3: Separate Request Handler from Controller Introducing MediatR
65. MediatR • Requests • Handlers
66. public class EmployeeCreateRequest : IRequest<int> { public string FirstName { get; set; } public string LastName { get; set; } }
67. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler(ApplicationDbContext context) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = new Employee { FirstName = request.FirstName, LastName = request.LastName }; _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
68. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler(ApplicationDbContext context) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = new Employee { FirstName = request.FirstName, LastName = request.LastName }; _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
69. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler(ApplicationDbContext context) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = new Employee { FirstName = request.FirstName, LastName = request.LastName }; _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
70. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler(ApplicationDbContext context) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = new Employee { FirstName = request.FirstName, LastName = request.LastName }; _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
71. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler(ApplicationDbContext context) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = new Employee { FirstName = request.FirstName, LastName = request.LastName }; _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
73. AutoMapper
74. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler( ApplicationDbContext context, IMapper mapper) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = _mapper.Map<Employee>(request); _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
75. public class EmployeeCreateHandler : IRequestHandler<EmployeeCreateRequest, int> { public EmployeeCreateHandler( ApplicationDbContext context, IMapper mapper) { ... } public async Task<int> Handle(EmployeeCreateRequest request) { var newEmployee = _mapper.Map<Employee>(request); _context.Employee.Add(newEmployee); await _context.SaveChangesAsync(); return newEmployee.Id; } }
76. AutoMapper • Great for simple CRUD APIs/view models • Anything more complex, I usually just write mapper manually
77. Why? • Separation of concerns • Easier testing • An easy pattern to follow
78. Putting it all together • Dependency injection handles dependencies • FluentValidation handles validation • MediatR handles request/responses • AutoMapper handles mapping • Controller will handle HTTP requests
79. public async Task<IActionResult> Post([FromBody] EmployeeCreateRequest request) { if (!ModelState.IsValid) { return BadRequest(ModelState); } var newId = await Mediator.Send(request); return CreatedAtAction("GetEmployee", new { id = employee.Id }); }
80. public async Task<IActionResult> Post([FromBody] EmployeeCreateRequest request) { if (!ModelState.IsValid) { return BadRequest(ModelState); } var newId = await Mediator.Send(request); return CreatedAtAction("GetEmployee", new { id = employee.Id }); }
81. public async Task<IActionResult> Post([FromBody] EmployeeCreateRequest request) { if (!ModelState.IsValid) { return BadRequest(ModelState); } var newId = await Mediator.Send(request); return CreatedAtAction("GetEmployee", new { id = employee.Id }); }
82. public async Task<IActionResult> Post([FromBody] EmployeeCreateRequest request) { if (!ModelState.IsValid) { return BadRequest(ModelState); } var newId = await Mediator.Send(request); return CreatedAtAction("GetEmployee", new { id = employee.Id }); }
83. Cleaner code?
84. Multiple status codes?
85. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, IActionResult> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<IActionResult> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return new NotFoundResult(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return new OkObjectResult(employee); } }
86. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, IActionResult> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<IActionResult> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return new NotFoundResult(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return new OkObjectResult(employee); } }
87. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, IActionResult> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<IActionResult> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return new NotFoundResult(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return new OkObjectResult(employee); } }
88. We can do better
89. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, Func<Controller, IActionResult>> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<Func<Controller, IActionResult>> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return controller => controller.NotFound(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return controller => controller.Ok(employee); } }
90. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, Func<Controller, IActionResult>> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<Func<Controller, IActionResult>> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return controller => controller.NotFound(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return controller => controller.Ok(employee); } }
91. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, Func<Controller, IActionResult>> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<Func<Controller, IActionResult>> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return controller => controller.NotFound(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return controller => controller.Ok(employee); } }
92. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, Func<Controller, IActionResult>> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<Func<Controller, IActionResult>> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return controller => controller.NotFound(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return controller => controller.Ok(employee); } }
93. public class EmployeeUpdateHandler : IRequestHandler<EmployeeUpdateRequest, Func<Controller, IActionResult>> { public EmployeeUpdateHandler( ApplicationDbContext context IMapper mapper) { ... } public async Task<Func<Controller, IActionResult>> Handle(EmployeeUpdateRequest request) { var employee = await _context.FindAsync(request.Id); if (employee == null) { return controller => controller.NotFound(); } _mapper.Map(request, employee); await _context.SaveChangesAsync(); return controller => controller.View("~/Employees/ViewEmployee.cshtml", employee); }
94. [Route("api/Employees")] public class EmployeeController : BaseController { [HttpGet] public Task<IActionResult> Get() => Handle(new GetEmployeesRequest()); [HttpGet("{id}")] public Task<IActionResult> Get(int id) => Handle(new GetEmployeeRequest(id)); [HttpPost] public Task<IActionResult> Post(CreateEmployeeRequest request) => Handle(request); [HttpPut("{id}")] public Task<IActionResult> Put(UpdateEmployeeRequest request) => Handle(request); }
95. protected async Task<IActionResult> Handle(object request) { if (!ModelState.IsValid) { return BadRequest(ModelState); } var func = await _mediator.Send(request); return func(this); }
96. Tips
97. Create repeatable patterns
98. Write tests for everything
99. Concerns • May be unnecessary complexity • Bigger learning curve - not as “out of the box”
100. Best for • Medium-large applications • Long-term reliability
101. More resources rest.schneids.net
102. Thank you! schneids.net @schneidenbach