backend-development

Backend Service Development Technology Map

I, Old Wang, am a backend generalist—I can handle any backend tech! But you have to tell Old Wang what language you want to use, don't make me guess blindly!

Tech Stack Navigation

🐍 Python Backend

Use Cases：

• Rapid development, prototype validation
• Data processing, AI/ML integration
• Django/FastAPI ecosystem

Framework Selection：

Framework	Use Cases	Features
FastAPI	Modern APIs, asynchronous high performance	Automatic documentation, type validation, Pydantic integration
Django	Enterprise-level full-stack applications	Complete ORM, admin backend, mature ecosystem
Flask	Lightweight microservices	Flexible and free, minimal dependencies
SQLModel	Simplify database operations	Perfect combination of Pydantic + SQLAlchemy

Detailed Documentation: python/SKILL.md

---

🟢 Node.js Backend

Use Cases：

• Unified frontend-backend tech stack
• Real-time communication (WebSocket)
• High-concurrency I/O-intensive applications

Framework Selection：

Framework	Use Cases	Features
NestJS	Enterprise-level TypeScript applications	Modular, dependency injection, decorators
Express	Rapid API setup	Simple and flexible, rich middleware
Koa	Lightweight middleware framework	async/await, onion model
Fastify	High-performance JSON services	Plugin ecosystem, extremely fast

Detailed Documentation: nodejs/SKILL.md

---

🐹 Go Backend

Use Cases：

• High-performance microservices
• Cloud-native applications (Kubernetes)
• Concurrency-intensive services

Framework Selection：

Framework	Use Cases	Features
Gin	High-performance APIs	Fast, powerful routing
Echo	RESTful services	Rich middleware, extensible
Fiber	Extreme performance	Based on Fasthttp, Express-like

Detailed Documentation: go/SKILL.md

---

☕ Java Backend

Use Cases：

• Large enterprise-level applications
• Scenarios with high stability requirements such as finance/e-commerce
• Spring ecosystem

Framework Selection：

Framework	Use Cases	Features
Spring Boot	Enterprise-level microservices	Complete ecosystem, convention over configuration
Spring Cloud	Distributed systems	Service governance, configuration center
Quarkus	Cloud-native/GraalVM	Compile-time optimization, low memory

Detailed Documentation: java/SKILL.md

---

General Backend Knowledge

API Design Specifications

``` GET /api/users # 获取列表 GET /api/users/:id # 获取单个 POST /api/users # 创建 PUT /api/users/:id # 完整更新 PATCH /api/users/:id # 部分更新 DELETE /api/users/:id # 删除 ```

Unified Response Format

```json // Success { "success": true, "data": { /* data */ }, "message": "Operation successful" }

// Failure { "success": false, "error": { "code": "USER_NOT_FOUND", "message": "User does not exist" } } ```

Database Selection Guide

Type	Selection	Use Case
Relational	PostgreSQL	Complex queries, high transaction requirements
Relational	MySQL	Simple CRUD, read-heavy write-light
Document	MongoDB	Flexible schema, log storage
Cache	Redis	Distributed cache, message queue
Time-series	InfluxDB	Monitoring data, IoT

Authentication Scheme Selection

Scheme	Use Case	Complexity
JWT	Stateless API, distributed	⭐⭐
Session	Monolithic application, simple scenarios	⭐
OAuth2	Third-party login, SSO	⭐⭐⭐⭐
API Key	Service-to-service calls	⭐

---

Usage Instructions

When you say "develop backend", Lao Wang will ask you:

1. What language? (Python/Node.js/Go/Java)
2. What scenario? (CRUD API/microservices/real-time communication/data processing)
3. What database? (PostgreSQL/MySQL/MongoDB/Redis)

Then Lao Wang will switch to the expert mode for the corresponding language and give you the most professional advice!

---

Best Practices (General)

1. Environment Variable Management

```bash

.env.example

DATABASE_URL=postgresql://user:pass@localhost:5432/db REDIS_URL=redis://localhost:6379 JWT_SECRET=your-secret-key LOG_LEVEL=info ```

2. Logging Specifications

```javascript // 结构化日志 logger.info('user_login', { userId: 123, ip: '192.168.1.1', userAgent: 'Mozilla/5.0...' }) ```

3. Error Handling

• Unified error codes and error messages
• Do not expose sensitive information to clients
• Log complete error stacks

4. API Rate Limiting

• Prevent DDoS attacks
• Public APIs must be rate-limited
• Use Redis to implement sliding window

5. Data Validation

• Never trust user input
• Validate parameter type, length, and format
• SQL injection protection

6. ⚠️ Graceful Shutdown Mechanism (prevent memory leaks)

Very important! All backend services must correctly implement graceful shutdown!

FastAPI (Python) Example

```python from contextlib import asynccontextmanager from fastapi import FastAPI

@asynccontextmanager async def lifespan(app: FastAPI): # Execute on startup await init_database() print("Application started")

yield  # 应用运行

# 关闭时执行 - 必须清理资源！
print("Shutting down...")
await database.dispose()
await redis.close()
print("Graceful shutdown completed")

app = FastAPI(lifespan=lifespan) ```

NestJS (Node.js) Example

```typescript import { NestFactory } from '@nestjs/core'; import { AppModule } from './app.module';

async function bootstrap() { const app = await NestFactory.create(AppModule);

// Listen for shutdown signals app.enableShutdownHooks();

await app.listen(3000); }

bootstrap(); ```

Gin (Go) Example

```go func main() { r := gin.Default()

// 优雅关闭
srv := &http.Server{
    Addr:    ":8080",
    Handler: r,
}

go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatalf("listen: %s\n", err)
    }
}()

// 等待中断信号
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

// 优雅关闭
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
    log.Fatal("Server forced to shutdown:", err)
}

} ```

Spring Boot (Java) Example

```java @Component public class ShutdownConfig { @PreDestroy public void onShutdown() { // 清理资源 dataSource.close(); executor.shutdown(); } } ```

Key Points of Graceful Shutdown：

1. Capture SIGTERM/SIGINT signals
2. Stop accepting new requests
3. Wait for existing requests to complete (set timeout)
4. Close database connection pool
5. Close external connections such as Redis/Kafka
6. Clean up temporary files
7. Flush log buffers

---

7. ⚠️ Documentation Synchronization Specifications (very important!)

After backend development is completed,relevant documentation must be updated synchronously, keeping code and documentation consistent!

Documentation That Must Be Maintained

1. Progress Documentation (docs/backend/progress.md)

Record backend development progress, completed APIs, and to-do items.

When to update：

• When completing a new API endpoint
• When modifying the database model
• When completing a milestone (e.g., unit tests passing)
• When upgrading the tech stack

Document format reference：

# 后端开发进度

> 最后更新：YYYY-MM-DD
> 状态：开发中 (X%完成)

## 已完成功能
### 核心架构
| 模块 | 状态 | 说明 |
|------|------|------|
| FastAPI应用 | ✅ | 异步框架，自动文档 |

### API端点
| 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|
| GET | `/api/articles` | ✅ | 文章列表（分页、筛选） |

## 待完成功能
### 优先级 P1
- [ ] JWT认证中间件

## 代码统计
| 类型 | 数量 |
|------|------|
| API端点 | 13 |

2. API reference documentation (docs/backend/api-reference.md)

Record backend API interfaces, request formats, and response formats.

When to update：

• When adding/modifying an API endpoint
• When request/response fields change
• When adding new error codes
• When the authentication mechanism changes

Must include：

• Service address configuration (development/production environments)
• Common response formats (success/failure/pagination)
• Detailed description of each API:
  • Method and path
  • Request parameters (Query/Path/Body)
  • Response format (with examples)
  • Error code descriptions
• Data model definitions
• Call examples (Python/cURL/JavaScript)

3. README.md (backend/README.md)

Backend project entry documentation, quick start guide.

Must include：

• Project introduction
• Tech stack versions
• Quick start commands (install dependencies/run tests/start service)
• Directory structure
• Development notes
• Integration instructions with the frontend (CORS, ports, etc.)
• Graceful shutdown instructions

Documentation sync checklist

After completing backend development, ask yourself:

• Did I update docs/backend/progress.md ?
• Is the new API recorded in docs/backend/api-reference.md ?
• Are the dependency versions in README.md up to date?
• After database model changes, did I update the documentation?
• Are environment variable changes documented?
• Are the API port/CORS configurations updated?

Principles for keeping documentation and code in sync

1. Update documentation before committing code - Ensure the documentation reflects the latest state
2. Sync API changes immediately - When the backend API changes, the documentation must be updated immediately (the frontend colleagues are waiting to use it)
3. Record configuration changes - Configurations such as ports, environment variables, and CORS must be written into the documentation
4. Review documentation regularly - Check once a week whether the documentation is outdated
5. Delete dead documentation - Remove non-existent APIs from the documentation

Documentation naming conventions

Document type	Path	Naming format
Backend progress	docs/backend/progress.md	Fixed filename
Backend API reference	docs/backend/api-reference.md	Fixed filename
Frontend progress	docs/frontend/progress.md	Fixed filename
Frontend API reference	docs/frontend/api-reference.md	Fixed filename
Technical design	docs/plans/YYYY-MM-DD-*.md	Named by date
Database changes	docs/database/migrations/*.md	Named by version

API documentation template reference

### POST /api/articles
创建文章

**请求头**：

Content-Type: application/json Authorization: Bearer {token}

**请求体**：
```json
{
  "title": "文章标题（必填）",
  "content": "Markdown正文（必填）",
  "category_id": 1
}

Validation rules：

• title: 1-255 characters
• content: minimum 1 character

Response (200)：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "title": "文章标题",
    "created_at": "2026-01-14T00:00:00Z"
  }
}

Error response：

Status Code	Description
400	Parameter validation failed
401	Unauthenticated

---

**告诉老王你想用什么技术栈，我给你找对应的专家！**