Centralize Validation Messages & Remove Duplication In DTOs

Oct 24, 2025 by SLV Team 60 views

Goal

The primary goal here is to centralize validation messages and eliminate duplication across your Data Transfer Objects (DTOs). This approach ensures that error texts are consistent, easier to maintain, and ready for internationalization (i18n). By having a single source of truth for these messages, you reduce the risk of inconsistencies and make updates much more manageable.

When you centralize your validation messages, you are essentially creating a single point of reference for all error messages related to data validation. This means that if you need to change a message, you only need to change it in one place, and the changes will be reflected throughout your application. This not only saves time but also reduces the risk of introducing errors. Maintaining consistency is crucial because it ensures that users receive the same feedback regardless of where the error occurs, leading to a better user experience. Furthermore, having all validation messages in one place makes it easier to prepare your application for internationalization. You can easily translate the messages into different languages without having to hunt for them throughout your codebase. This is a significant advantage when you are targeting a global audience. Centralizing validation messages also promotes code reuse. Instead of duplicating the same messages across multiple DTOs, you can reference them from a central location. This reduces code clutter and makes your codebase more maintainable. In summary, centralizing validation messages is a best practice that promotes consistency, maintainability, and internationalization readiness. It is an essential step in building robust and scalable applications.

Scope

The scope of this task focuses on externalizing validation messages specifically for the name field rules within ItemCreateRequest and ItemUpdateRequest. Optionally, we can introduce a composed constraint @ValidName to bundle @NotBlank and @Size annotations into one, streamlining the validation process. The key here is to avoid any changes to the existing behavior; we're only refactoring where the messages and constraints are located.

When defining the scope, it's crucial to be precise about which parts of the application will be affected. In this case, we are specifically targeting the name field in ItemCreateRequest and ItemUpdateRequest. By limiting the scope, we can focus our efforts and ensure that the changes are well-contained. Externalizing validation messages involves moving the messages from the DTOs to a separate file, such as messages.properties. This makes it easier to manage and maintain the messages. The optional introduction of a composed constraint @ValidName is a way to further simplify the validation process. By bundling @NotBlank and @Size annotations into one, we can reduce code duplication and make the DTOs more readable. However, it's important to note that this is an optional step and should only be done if it provides a clear benefit. The most important aspect of the scope is to avoid any changes to the existing behavior. We want to ensure that the refactoring does not introduce any new bugs or unexpected side effects. This can be achieved by thoroughly testing the changes and ensuring that all tests pass. In summary, the scope of this task is well-defined and focuses on refactoring the validation messages and constraints for the name field in specific DTOs, while avoiding any changes to the existing behavior. This approach ensures that the changes are manageable and do not introduce any new issues.

Tasks

Let's break down the tasks required to achieve our goal. Here’s a checklist to guide you:

[ ] Add messages file
- Create src/main/resources/messages.properties
- Add keys:
  - item.name.required = name is required
  - item.name.length = name must be 2–40 chars
  - item.name.invalid = invalid name
[ ] Refactor DTOs to use keys
- Update ItemCreateRequest and ItemUpdateRequest:
  - @NotBlank(message = "{item.name.required}")
  - @Size(min=2, max=40, message = "{item.name.length}")
[ ] (Optional) Add composed constraint
- Create @ValidName annotation that composes @NotBlank + @Size using the same message keys
- Replace field annotations in both DTOs with @ValidName
[ ] Build & test
- mvn -q test (ensure all tests pass; update any tests that assert exact messages)
[ ] PR
- Open PR with atomic commits; Squash & merge
- PR body: Refs #<this-issue-id> and (if relevant) Refs #5

Detailed Breakdown of Tasks

Let's dive a bit deeper into each of these tasks to make sure we're all on the same page, alright?

Add messages file: First off, you'll need to create a messages.properties file in the src/main/resources directory. This file will serve as the central repository for all our validation messages. Inside this file, you'll add key-value pairs for each message. For example, item.name.required = name is required defines a key (item.name.required) and its corresponding message (name is required). The key should be descriptive and follow a consistent naming convention to make it easy to understand and maintain. The message should be clear and concise, providing enough information for the user to understand the error. This file is crucial because it allows us to externalize the messages, making them easier to manage and translate.
Refactor DTOs to use keys: Next up, you'll modify the ItemCreateRequest and ItemUpdateRequest DTOs to reference the keys defined in the messages.properties file. Instead of hardcoding the error messages directly in the annotations, you'll use the {key} syntax to reference the corresponding message in the messages.properties file. For example, @NotBlank(message = "{item.name.required}") tells Spring to look up the message associated with the item.name.required key in the messages.properties file. This ensures that the DTOs are decoupled from the actual messages, making it easier to change the messages without modifying the DTOs. It also promotes code reuse, as the same message can be used in multiple places without duplication. This refactoring is a key step in centralizing the validation messages and making them more maintainable.
(Optional) Add composed constraint: This task is optional but highly recommended. It involves creating a custom annotation called @ValidName that combines the @NotBlank and @Size annotations into one. This annotation can then be used to replace the individual annotations in the DTOs, making the code cleaner and more readable. The @ValidName annotation should be defined with the same message keys as the individual annotations. This means that it should use {item.name.required} for the @NotBlank constraint and {item.name.length} for the @Size constraint. By composing these constraints into a single annotation, you can simplify the DTOs and reduce code duplication. This also makes it easier to enforce a consistent set of validation rules across multiple DTOs. The @ValidName annotation should be placed in a separate file and annotated with @Constraint to indicate that it is a custom validation constraint. This task is optional because it requires more effort to implement, but it can provide significant benefits in terms of code clarity and maintainability.
Build & test: After making the changes, it's essential to build and test the application to ensure that everything is working as expected. Run mvn -q test to execute the unit tests. Make sure that all tests pass and that no new errors have been introduced. If any tests fail, update them to assert the correct messages. This is important because the messages may have changed as a result of the refactoring. You should also test the application manually to ensure that the validation is working correctly and that the error messages are being displayed as expected. Pay close attention to the edge cases and boundary conditions to ensure that the validation is robust and reliable. Testing is a critical step in the development process, and it should not be skipped or rushed. It helps to identify and fix errors early, before they can cause problems in production.
PR: Once you're confident that the changes are correct and the tests are passing, it's time to open a pull request (PR). Make sure to create atomic commits, each representing a logical unit of work. This makes it easier to review the changes and understand the reasoning behind them. Squash the commits into a single commit before merging to keep the commit history clean and concise. In the PR body, include references to the related issues, such as Refs #<this-issue-id> and Refs #5. This helps to track the progress of the issues and ensures that the PR is properly linked to the relevant tasks. The PR should be reviewed by other members of the team to ensure that the changes are correct and that they meet the required standards. Be responsive to feedback and make any necessary changes to address the comments. Once the PR has been approved, it can be merged into the main branch. Opening a PR is an important step in the development process because it allows for collaboration and code review, ensuring that the changes are of high quality and that they meet the requirements of the project.

Definition of Done

To ensure we're all on the same page, let's define what "Done" looks like:

[ ] messages.properties present and loaded by Spring
[ ] DTOs reference message keys (no duplicated strings in code)
[ ] (Optional) @ValidName annotation in place and used
[ ] No behavior changes; only message source moved
[ ] Tests pass locally; repo compiles
[ ] PR merged and project board card moved to Done

Elaborating on the Definition of Done

Okay, so let's really nail down what we mean by "Done" for this task. It's not just about ticking boxes; it's about ensuring we've achieved a solid, maintainable, and testable solution. Here's a more detailed look at each point:

messages.properties present and loaded by Spring: This isn't just about having the file exist. We need to be absolutely sure that Spring is actually picking it up and using it. You can verify this by running the application and checking that the validation messages are being displayed correctly. If the messages are not being displayed, then there may be a problem with the configuration. Double-check the location of the file and make sure that it is in the correct directory. Also, make sure that the file is included in the classpath. You can do this by adding it to the src/main/resources directory in your project. If the file is still not being loaded, then there may be a problem with the Spring configuration. Check the application context file and make sure that the messageSource bean is properly configured. This is a critical step in ensuring that the validation messages are being loaded correctly and that the application is working as expected. Without this, the validation messages will not be displayed, and the application will not be able to validate the data correctly.
DTOs reference message keys (no duplicated strings in code): This is super important, guys. We're aiming to kill off any hardcoded strings in the DTOs. Every single validation annotation in those DTOs should be pointing to a key in messages.properties. No exceptions. This ensures that all the validation messages are centralized in one place, making it easier to maintain and update them. It also helps to prevent inconsistencies in the messages, as there is only one source of truth. To verify this, you should carefully review the DTOs and make sure that all the validation annotations are using the {key} syntax. You should also search the codebase for any hardcoded validation messages and replace them with references to the messages.properties file. This is a key step in ensuring that the validation messages are centralized and that the code is clean and maintainable. Without this, the validation messages will be scattered throughout the codebase, making it difficult to maintain and update them.
(Optional) @ValidName annotation in place and used: If you went for the custom annotation, make sure it's not just sitting there. It needs to be actively replacing the @NotBlank and @Size annotations in the DTOs. Double-check that you've removed the original annotations and that the @ValidName annotation is doing its job. This is important because the @ValidName annotation is responsible for encapsulating the validation logic and making the code more readable. If the @ValidName annotation is not being used, then the code will be more verbose and difficult to maintain. To verify this, you should carefully review the DTOs and make sure that the @ValidName annotation is being used in place of the @NotBlank and @Size annotations. You should also run the application and test the validation to make sure that the @ValidName annotation is working correctly. This is a key step in ensuring that the code is clean and maintainable and that the validation logic is encapsulated in a single annotation.
No behavior changes; only message source moved: This is a big one. The validation should work exactly the same as before. The only thing that should have changed is where the messages are stored. To verify this, you should run the application and test the validation thoroughly. Make sure that all the validation rules are being enforced and that the error messages are being displayed correctly. You should also compare the behavior of the application before and after the changes to make sure that there are no unexpected side effects. This is a critical step in ensuring that the changes are correct and that the application is working as expected. Without this, there is a risk of introducing new bugs or breaking existing functionality.
Tests pass locally; repo compiles: Pretty self-explanatory, but crucial. All your tests need to be green, and the code needs to compile without any errors. This is the bare minimum for any code change. To verify this, you should run all the tests in the project and make sure that they all pass. You should also run the build process to make sure that the code compiles without any errors. This is a basic sanity check that ensures that the code is working correctly and that there are no syntax errors or other issues. Without this, there is a risk of introducing broken code into the codebase.
PR merged and project board card moved to "Done": Finally, the PR needs to be merged into the main branch, and the corresponding card on the project board needs to be moved to the "Done" column. This indicates that the task has been completed and that the changes have been integrated into the codebase. This is the final step in the process and ensures that the task is properly tracked and that the team is aware that it has been completed.

Commit Suggestions

Here are some suggested commit messages to keep your commit history clean and informative:

chore(i18n): add messages.properties for validation texts
refactor(validation): use message keys in Item DTOs
(optional) feat(validation): introduce @ValidName composed constraint

Refs #5