48 lines
1.6 KiB
Markdown
48 lines
1.6 KiB
Markdown
# pkg/server/api/console/v1
|
|
|
|
GraphQL API using `gqlgen`. Schema-first approach.
|
|
|
|
## Generated vs hand-written
|
|
|
|
| File | Type | Notes |
|
|
|------|------|-------|
|
|
| `schema.graphql` | Hand-written | GraphQL schema definition |
|
|
| `gqlgen.yaml` | Hand-written | Codegen config |
|
|
| `resolver.go` | Hand-written | Root `Resolver` struct and `NewMux` |
|
|
| `graphql_handler.go` | Hand-written | Handler setup |
|
|
| `v1_resolver.go` | Generated stubs | Resolver method implementations (edit the bodies) |
|
|
| `schema/schema.go` | **Generated — DO NOT EDIT** | Executable schema |
|
|
| `types/types.go` | **Generated — DO NOT EDIT** | Type definitions |
|
|
|
|
## Important rules
|
|
|
|
- **Never edit generated files** (`schema/schema.go`, `types/types.go`). Only edit `schema.graphql` and resolver bodies.
|
|
- **After any change to `schema.graphql`**, always run codegen:
|
|
|
|
```
|
|
go generate ./pkg/server/api/console/v1
|
|
```
|
|
|
|
## Resolver pattern
|
|
|
|
Every resolver method follows this sequence:
|
|
|
|
1. **Authorize** — `r.authorize(ctx, obj.ID, probo.ActionXxxGet)`
|
|
2. **Get service** — `prb := r.ProboService(ctx, tenantID)`
|
|
3. **Call service** — `result, err := prb.Foo.Bar(ctx, ...)`
|
|
4. **Handle error** — wrap or panic on unexpected errors
|
|
|
|
## Pagination
|
|
|
|
Relay cursor pattern:
|
|
- `page.Cursor[OrderField]` for cursor handling
|
|
- Connection types (`*Connection`) with `ParentID`, `Resolver`, `Filter` fields
|
|
|
|
## Custom scalars
|
|
|
|
`ID`, `Datetime`, `CursorKey`, `Duration`, `BigInt`, `EmailAddr` — mapped in `gqlgen.yaml`.
|
|
|
|
## Authentication middleware
|
|
|
|
`NewMux()` chains: session → API key → identity presence middlewares.
|