How y1jiong/qq-bot-backend works
Project type and purpose
• This is a standalone backend service (“qq-bot-backend”) written in Go.
• Its purpose is to act as a QQ-bot server supporting the OneBot11 protocol (CQ-codes), adapting clients like go-cqhttp and LLOneBot.
• It exposes HTTP and WebSocket endpoints, processes incoming messages/commands, applies business rules, interacts with PostgreSQL, and may call external services (e.g. Mojang).
File structure
Top-level directories and files:
• api/… – API-layer definitions for “command” and “message” interfaces (versioned v1).
• internal/controller/… – HTTP/WebSocket controllers that map API requests to service calls.
• internal/service/… – Service façade layer; orchestrates logic and DAO.
• internal/logic/… – Core business logic organized by domain (bot, command, event, file, group, namespace, etc.).
• internal/dao/… – Data access objects handling persistence, with internal subpackages for detailed SQL mappings.
• internal/model/… – Data models (DO = database objects, Entity = domain entities).
• manifest/… – Deployment scripts and PostgreSQL schema.
• utility/… – Shared helper functions (codec, webhook, limiting, etc.).
• main.go – Bootstraps server, loads config, starts HTTP/WebSocket listeners.
• config (hack.example/config.toml, manifest/config.example) – Application configuration.
README for additional insights
• Supports OneBot11 CQ-code message reporting formats.
• Adapted for go-cqhttp and LLOneBot.
• Project coding conventions (defer behavior, parameter validation order).
a. Main components
1. External Clients – go-cqhttp / LLOneBot (HTTP + WebSocket).
2. API Layer – Versioned command & message definitions (api/command, api/message).
3. Controller Layer – HTTP handlers and WebSocket connection management (internal/controller).
4. Service Layer – High-level operations orchestration (internal/service).
5. Business Logic Layer – Domain-specific logic (internal/logic/*).
6. DAO Layer – Persistence adapters and repositories (internal/dao/*).
7. Data Store – PostgreSQL (manifest/postgresql).
8. External Third-Party Services – e.g. Mojang API (internal/logic/thirdparty).
9. Cross-cutting Utilities – Configuration, logging, metrics (otel), codec utilities.
10. Deployment & Configuration – Kubernetes/Shell Scripts, TOML configs in manifest.
b. Relationships and interactions
• Clients send requests (HTTP/WebSocket) → API Layer.
• API definitions route to Controller methods.
• Controllers call Service functions.
• Services invoke Business Logic and coordinate transactions.
• Logic layer may call other sub-modules (bot, event, file, etc.) and then call DAOs.
• DAO layer executes SQL against PostgreSQL and returns domain models.
• Logic returns results to Service → Controller → serializes response back via HTTP/WebSocket.
• Some logic modules call external HTTP APIs (e.g. Mojang).
• Configuration and telemetry (OpenTelemetry) loaded at startup via cfg logic.
c. Architectural patterns and principles
• Layered (onion) architecture: API → Controller → Service → Logic → DAO → DB.
• Clear separation of concerns: controllers are thin, all heavy lifting in logic.
• Versioned API definitions allow backward compatibility (api/command/v1).
• Internal packages prevent accidental external imports.
• Use of model DO vs entity for strict DB mapping vs domain representation.
• Utility packages for cross-cutting concerns (codec, rate limiting, runes).
d. Key technologies / frameworks
• Go (modules: go.mod).
• HTTP + Gorilla WebSocket (in controller/websocket.go) or standard library.
• PostgreSQL (manifest scripts, internal/dao uses database/sql or an ORM).
• TOML for configuration (hack.example/config.toml).
• OpenTelemetry for tracing (internal/logic/cfg/otel.go).
Diagramming recommendations
– External systems (clients, third-party APIs)
– Public interface components (API layer, controllers)
– Internal processing (service & logic layers)
– Data persistence (DAO & DB)
– Cross-cutting utilities (config, telemetry).
– Clients → API → Controller → Service → Logic → DAO → DB
– DAO → DB (query/response) → Logic → … → Clients
– Logic → External API (e.g. Mojang)
– Bootstrapping → Config Loader → Controllers & Telemetry
• Versioning on the API layer.
• Notes on deployment: config files, manifest scripts, database initialization.