MyGO/mygo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure server and web documentation into ADR files and a

Browse Source 
routing table
This commit is contained in:
Sunday
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/server/development.md
+55 -45
View File
@@ -1,9 +1,13 @@
# Development
# Server Development
## Prerequisites
- Go 1.26.2 (pinned in `mise.toml`)
- `mise` (https://mise.jdx.dev) — run `mise install` to install toolchain
- Go 1.26.2, pinned in `mise.toml`
- `mise` for installing the pinned toolchain
```bash
mise install
```
## Build
@@ -20,69 +24,75 @@ go test -v -run TestName ./internal/...
go test -race ./internal/repository ./internal/service ./internal/server
```
## Lint & Format
## Format and Static Analysis
```bash
go vet ./...
go fmt ./...
```
## Repository Review
Use the repository-scoped `$mygo-api-repo-review` skill for evidence-based architecture, design, security, resilience, data-consistency, performance, and implementation audits. Reviews are read-only unless fixes are requested separately.
Select one review mode:
- `diff` compares the current workspace, including relevant untracked files, with `HEAD`.
- `main` compares the current workspace with the merge base of `HEAD` and the local `main` branch without fetching remote refs.
- `full` reviews the current repository as a whole.
Optionally limit any mode to a target path, Go package, or logical component. For example:
```text
Use $mygo-api-repo-review in main mode with target internal/storage.
go vet ./...
```
## Dependencies
Run module cleanup after adding or removing imports:
```bash
go mod tidy # after adding/removing imports
go mod tidy
```
## Config
## Repository Review
Server config is loaded via viper from `config.yaml` (defaults in `internal/config/load.go`).
Use `$mygo-api-repo-review` for evidence-based architecture, design, security, resilience, data-consistency, performance, and implementation audits.
For SQLite, the repository preserves configured DSN parameters and adds
`_txlock=immediate`. Write transactions therefore reserve the database before
performing hierarchy or refresh-session reads, matching the locking assumptions
used by the repository commands. Keep this behavior when supplying a SQLite URI
such as `file:mygo.db?cache=shared`.
| Mode | Scope |
|------|-------|
| `diff` | Workspace, including relevant untracked files, compared with `HEAD` |
| `main` | Workspace compared with the merge base of `HEAD` and local `main` |
| `full` | Complete repository |
Reviews are read-only unless the user also requests fixes. A mode can target a path, Go package, or logical component.
## Configuration
The server reads `config.yaml` from the working directory when present. Environment variables use the `MYGO_` prefix and underscores, for example `MYGO_SERVER_PORT` and `MYGO_JWT_SECRET`.
```yaml
server:
host: 0.0.0.0
port: 10086
host: 0.0.0.0
port: 10086
database:
driver: sqlite3
sqlite:
path: data/mygo.db
driver: sqlite3
sqlite:
path: data/mygo.db
storage:
driver: local
local:
path: data/files
driver: local
max_upload_size: 0
local:
path: data/files
jwt:
secret: dev-secret-do-not-use-in-production
access_ttl: 15m
refresh_ttl: 168h
secret: dev-secret-do-not-use-in-production
access_ttl: 15m
refresh_ttl: 168h
log:
level: info
file_path: ""
file_level: debug
```
Environment variables use `MYGO_` prefix with underscore separators: `MYGO_SERVER_PORT=8080`, `MYGO_JWT_SECRET=...`
| Setting | Behavior |
|---------|----------|
| `database.driver` | Selects `sqlite3` or `postgres` |
| `storage.max_upload_size` | `0` allows any upload size; a positive byte count enables request and service limits |
| `jwt.secret` | Signs access and refresh tokens |
| `log.level` | Sets stderr logging to `debug`, `info`, `warn`, or `error` |
| `log.file_path` | Enables an additional text log file when set |
| `log.file_level` | Sets the file log level independently |
The default JWT secret is a development placeholder. At startup, MyGO replaces
it with an ephemeral runtime secret; set a stable `jwt.secret` or
`MYGO_JWT_SECRET` when tokens must survive restarts or when running multiple
instances.
PostgreSQL uses the `database.postgres` host, port, user, password, database name, and SSL mode fields defined in `internal/config`.
The SQLite connector preserves configured DSN parameters and sets `_txlock=immediate`. This setting establishes the transaction behavior required by hierarchy and refresh-session commands.
The default JWT secret is a development placeholder. Configuration loading replaces it with a random in-memory secret for the current process. Set a stable secret for multi-instance deployments and tokens that must survive a restart.