92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
# Error Handling Standards
|
|
|
|
## Philosophy
|
|
|
|
Fail fast with a consistent, machine-readable response. Handle errors at the controller boundary; let business logic return typed errors. Never silently swallow errors.
|
|
|
|
## Go API Response Pattern
|
|
|
|
All HTTP responses go through two helpers in `controllers/response.go`:
|
|
|
|
```go
|
|
// Success (always HTTP 200)
|
|
ReturnSuccess(ctx, common.SUCCESS_CODE, common.SUCCESS_MSG, data)
|
|
|
|
// Error (HTTP status == code parameter)
|
|
ReturnError(ctx, common.ERROR_AUTH_CODE, common.ERROR_ACCESS_FORBIDDEN_MSG, nil)
|
|
ctx.Abort() // always Abort() after ReturnError in middleware
|
|
return // always return immediately after ReturnError in handlers
|
|
```
|
|
|
|
**The early-return pattern is non-negotiable.** Every error path ends with `ReturnError(...); return`.
|
|
|
|
## HTTP Status Code Mapping
|
|
|
|
| Code | Constant | When to use |
|
|
|------|----------|-------------|
|
|
| 200 | `SUCCESS_CODE` | Successful operation |
|
|
| 201 | `CREATED` | Resource created |
|
|
| 400 | `INVALID_PARAMS_CODE` | Malformed or invalid input |
|
|
| 401 | `ERROR_AUTH_CHECK_TOKEN_CODE` | Missing or invalid JWT |
|
|
| 403 | `ERROR_AUTH_CODE` | Valid JWT but insufficient permission |
|
|
| 404 | `ERROR_NOT_FOUND_CODE` | Resource not found |
|
|
| 429 | `ERROR_TOO_MANY_REQUESTS_CODE` | Rate limit exceeded |
|
|
| 500 | `ERROR_CODE` | Unexpected server error |
|
|
|
|
All code constants are defined in `common/common.go`. Add new codes there — do not inline numeric literals in handlers.
|
|
|
|
## Structured Logging with Zap
|
|
|
|
Log at the call site before returning an error. Use typed field helpers — never `fmt.Sprintf` in zap calls.
|
|
|
|
```go
|
|
// Preferred pattern
|
|
logger.Error("rate limit exceeded",
|
|
zap.String("path", path),
|
|
zap.String("client_ip", ctx.ClientIP()),
|
|
zap.Int("errorcode", code),
|
|
)
|
|
|
|
// For error values
|
|
logger.Error("validate token error", zap.Error(err))
|
|
|
|
// For complex types
|
|
logger.Debug("permissions resolved", zap.Any("permsWithType", permsWithType))
|
|
```
|
|
|
|
**Log levels**:
|
|
- `Error` — operation failed, client or server fault
|
|
- `Warn` — recoverable edge case (e.g., retried operation succeeded)
|
|
- `Info` — key lifecycle events (server start, config load)
|
|
- `Debug` — diagnostic detail, disabled in production
|
|
|
|
**Never log**: JWT tokens, passwords, secret keys, or full request bodies containing sensitive data.
|
|
|
|
## C Error Propagation
|
|
|
|
Return negative errno-style codes for C daemon errors. Use the `errnox.h` definitions from `src/include/xce/`. Check and propagate immediately — do not continue on error:
|
|
|
|
```c
|
|
int rc = xce_send_request(&req);
|
|
if (rc < 0) {
|
|
log_error("send_request failed: %d", rc);
|
|
return rc;
|
|
}
|
|
```
|
|
|
|
## Input Validation Pattern
|
|
|
|
Validate at the controller boundary using a `preCheck{Resource}Request()` helper before touching services:
|
|
|
|
```go
|
|
func (c JobController) SubmitJob(ctx *gin.Context) {
|
|
req, err := preCheckSubmitJobRequest(ctx)
|
|
if err != nil {
|
|
ReturnError(ctx, common.INVALID_PARAMS_CODE, err.Error(), nil)
|
|
return
|
|
}
|
|
// ... service call
|
|
}
|
|
```
|
|
|
|
Keep `preCheck*` functions in the same file as the handler. They bind, validate, and return the typed request struct or an error.
|