Skip to content

development-standards.md

Latest commit

 

History

History
77 lines (58 loc) · 2.66 KB

development-standards.md

File metadata and controls

77 lines (58 loc) · 2.66 KB
Raw

Backend Development Standards

These standards are the public baseline for stackrivet-server.

Local Setup

docker compose up -d mysql redis
mvn install -DskipTests=true
mvn -pl stackrivet-app spring-boot:run

OpenAPI is served on the application port at /v3/api-docs and /swagger-ui.html, and both require a bearer token. Actuator is served on the separate management port, http://127.0.0.1:9090/actuator/health by default.

Module Boundaries

  • Each Maven module owns one responsibility.
  • Keep dependencies explicit and acyclic.
  • stackrivet-common must not depend on any other StackRivet module.
  • Cross-module communication uses APIs/SPIs, never direct mapper calls across module boundaries.

Java Style

  • Use JDK 21, Spring and established project helpers before adding dependencies.
  • Do not add Hutool or catch-all utility libraries.
  • Use explicit DTO/VO mapping or compile-time generated mapping; avoid reflective bean-copy shortcuts.
  • Use SLF4J. Do not use System.out.println in production code.
  • Keep comments short and useful; avoid restating obvious code.

API Rules

  • Base path is /api/v1.
  • Successful responses use R<T> or PageR<T>.
  • HTTP status remains meaningful; do not collapse all responses to 200.
  • Error codes are stable and never localized.
  • Pagination defaults to page=1, pageSize=20, max pageSize=200.

Security Rules

  • Protected endpoints require @PreAuthorize.
  • Add or update module.manifest.json when adding a permission.
  • Passwords are strongly hashed and never logged.
  • Tokens, secrets, storage credentials and signed URLs never appear in logs.
  • File access goes through Asset Service permission checks.

Database Rules

  • All schema changes go through Flyway.
  • Keep migrations deterministic and reviewable.
  • Do not manually patch production schema outside migrations.
  • MySQL and PostgreSQL SQL differences belong in their vendor-specific migration directories.

Async And Scheduler Rules

  • Documented long-running operations use stackrivet-task.
  • Generator apply stages files synchronously under the configured output root; do not document it as an async task unless the implementation changes.
  • Idempotency is required for async task submission.
  • Scheduler integration goes through the scheduler SPI. SnailJob is an optional adapter and is not part of the default app runtime.

Verification Gates

mvn -pl stackrivet-<module> -am test
mvn -pl stackrivet-app test -Dtest=ArchitectureTest
mvn verify

For storage changes, run local upload/download through the admin UI or API. The Community CLI doctor checks configuration presence only; it does not perform a live storage round-trip.