BrandaoFelipe opened a new pull request, #3029:
URL: https://github.com/apache/hugegraph/pull/3029
## Purpose of the PR
- close #2975
The purpose of this PR is to standardize and unify the REST API global error
response format across the core modules (`pd`, `server` and
`store/hg-store-node`) using the centralized `ApiResponse` envelope wrapper.
Currently, unhandled exceptions or module-specific errors could return
inconsistent formats or expose raw stack traces to the client. This tracking
change enforces a clean, predictable JSON error contract across different
frameworks used in the ecosystem (Jersey and Spring Boot), enhancing API
security and client-side error handling.
## Main Changes
This PR introduces centralized exception mapping logic across two distinct
sub-framework layers within the project:
### 1. `hugegraph-server` module (Jersey / JAX-RS)
* **`HugeExceptionMapper`**: Intercepts all `HugeException` occurrences. It
safely resolves the underlying root cause using a recursive `rootCause()`
lookup and maps internal core errors directly to appropriate HTTP Status Codes
(e.g., `IllegalArgumentException` -> 400 Bad Request, `NoSuchElementException`
-> 404 Not Found) wrapped cleanly inside `ApiResponse`.
* **`GenericExceptionMapper`**: Implemented as a top-level global catch-all
provider for `Exception.class` to prevent infrastructure leakages, mapping
unexpected exceptions to a secure HTTP 500 `"An unexpected error occurred"`
message payload.
### 2. `hugegraph-store` module (`hg-store-node` sub-module / Spring Boot)
* **`StoreExceptionHandler`**: Created using Spring's
`@RestControllerAdvice` to intercept `HgStoreException`. It dynamically parses
the exception's internal error `code` to differentiate client errors from
infrastructure faults based on explicit ranges:
* Codes `[1200, 1300)` (e.g., RocksDB storage failures) -> **500 Internal
Server Error** (logged as `SEVERE/ERROR` with full stack trace).
* Codes `[1000, 1200)` (e.g., Unsupported data formats) -> **400 Bad
Request** (logged cleanly as a `WARNING` message).
* **`GenericExceptionMapper`**: Added as a fallback interceptor for standard
`Exception.class` instances inside the store node rest controllers to ensure
uniform 500 error envelopes using the Log4j wrapper.
### 3. `hugegraph-pd` module (`hg-pd-service` sub-module / Spring Boot)
* **`PdExceptionHandler`**: Implemented via `@RestControllerAdvice` to
handle metadata and coordination cluster exceptions (`PDException`).
Centralizes cluster control plane failure logging (Raft state, partition
routing) and converts them into the unified `ApiResponse` schema.
* **Catch-All Filter**: Includes standard `Exception.class` mapping to
gracefully mask unhandled runtime infrastructure glitches with a generic `"An
unexpected error occurred in the cluster control plane"` feedback text.
## Verifying these changes
- [x] Need tests and can be verified as follows:
- Executed `mvn clean compile -DskipTests` from the root directory to
confirm proper multi-module compile-time dependency alignment (validating
`ApiResponse` cross-package visibility inside `hg-store-node`).
- Validated error response payloads against the unified schema structure
ensuring it adheres to the contract:
```json
{
"status": 400,
"message": "Specific validation/error message string",
"data": null,
"statusText": "Bad Request"
}
```
## Does this PR potentially affect the following parts?
- [ ] Dependencies
- [ ] Modify configurations
- [x] The public API
- [ ] Other affects (typed here)
- [ ] Nope
## Documentation Status
- [ ] `Doc - TODO`
- [ ] `Doc - Done`
- [x] `Doc - No Need`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
