97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
# Repository Guidelines
|
|
|
|
This repository is a Maven multi-module Spring Boot microservices system for an Online Judge (AIOJ). Use the notes below as the contributor guide for structure, workflow, and expectations.
|
|
|
|
## Tech Stack (Reference)
|
|
|
|
- Java 17
|
|
- Spring Boot 3.5.7
|
|
- Spring Cloud 2025.0.0
|
|
- Spring Cloud Alibaba 2025.0.0.0
|
|
- Maven build, Spring Java Format, JIB for Docker images
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
- Root `pom.xml` aggregates all modules.
|
|
- Shared libraries live in `aioj-backend-common`:
|
|
- `aioj-backend-common-bom` (dependency management)
|
|
- `aioj-backend-common-core` (core utilities + Spring extensions)
|
|
- `aioj-backend-common-security` (JWT/Spring Security)
|
|
- `aioj-backend-common-feign` (OpenFeign + Sentinel integration)
|
|
- `aioj-backend-common-log` (AOP logging)
|
|
- `aioj-backend-common-mybatis` (MyBatis extensions)
|
|
- `aioj-backend-common-starter` (auto-config starter)
|
|
- Service modules live at the repo root:
|
|
- `aioj-backend-gateway`, `aioj-backend-auth`, `aioj-backend-user-service`,
|
|
`aioj-backend-upms`, `aioj-backend-file-service`,
|
|
`aioj-backend-judge-service`, `aioj-backend-question-service`,
|
|
`aioj-backend-ai-service`, `aioj-backend-blog-service`
|
|
- Supporting folders include `docs`, `db`, `sentinel`, `logs`, `uploads`, and `generator`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Use Maven from the repo root:
|
|
|
|
```bash
|
|
mvn clean compile # build all modules (no tests)
|
|
mvn clean install # build + run tests
|
|
mvn clean compile -pl aioj-backend-auth # build a single module
|
|
mvn clean install -DskipTests # build all modules, skip tests
|
|
mvn spring-boot:run -pl aioj-backend-gateway # run a single service
|
|
mvn test -pl aioj-backend-user-service # test a single service
|
|
mvn spring-javaformat:apply # format code
|
|
mvn spring-javaformat:check # verify formatting
|
|
```
|
|
|
|
Docker image build (JIB):
|
|
|
|
```bash
|
|
mvn package jib:build -pl <module-name> # build & push
|
|
mvn package jib:buildTar -pl <module-name> # build tar
|
|
```
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
- Follow existing formatting and run `mvn spring-javaformat:apply` before submitting changes.
|
|
- Indentation follows Java defaults (4 spaces; no tabs unless already present).
|
|
- Use standard Java naming: `PascalCase` for classes, `camelCase` for methods/fields, `UPPER_SNAKE_CASE` for constants.
|
|
- Controllers: `<Resource>Controller`; Services: `<Resource>Service` / `<Resource>ServiceImpl`;
|
|
Mappers: `<Resource>Mapper`; DTOs: `<Operation><Resource>DTO`.
|
|
- Module names follow the `aioj-backend-*` pattern; keep new module names consistent.
|
|
|
|
## Development Guidelines
|
|
|
|
- Service modules should depend on common modules, not on other service modules.
|
|
- Use Feign clients for inter-service communication.
|
|
- Keep classes focused and single-purpose; prefer Lombok to reduce boilerplate.
|
|
- Validate and sanitize user input; use `@PreAuthorize` for method security.
|
|
- Use custom exceptions + global handlers; return consistent DTO responses.
|
|
- Externalize configuration; use Nacos for centralized config management.
|
|
- Never commit sensitive credentials.
|
|
|
|
## Architecture Notes
|
|
|
|
- Auth uses JWT via `common-security`.
|
|
- Gateway handles routing, auth checks, Sentinel-based flow control.
|
|
- Question service uses Chain of Responsibility for validation.
|
|
- Sentinel + Nacos provide dynamic flow control and rules.
|
|
- Redis used for cache/session; MyBatis for persistence.
|
|
- Blog service supports Markdown (Flexmark) + Redis caching.
|
|
|
|
## Testing Guidelines
|
|
|
|
- Tests live under `src/test/java` in each module.
|
|
- Name tests clearly after the unit under test (e.g., `UserServiceTest`).
|
|
- Run `mvn test` for full coverage or `mvn test -pl <module>` for targeted runs.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
- Commit messages follow a conventional prefix pattern (e.g., `feat: add rate limiting`, `refactor: simplify DTO mapping`). Keep the subject imperative and concise.
|
|
- PRs should include: a short summary, affected services/modules, testing performed, and any config or port changes.
|
|
- If a change affects API behavior or configuration, update `README.md` or relevant docs.
|
|
|
|
## Local Service Ports (Reference)
|
|
|
|
- Gateway `18085`, Auth `18081`, User `18082`, UPMS `18083`, File `18066`.
|
|
Update this list if you add or change service ports.
|