universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-CN/options/project-structure/java.md

@@ -0,0 +1,213 @@
+---
+source: ../../../../options/project-structure/java.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Java 专案结构
+
+> **语言**: [English](../../../../options/project-structure/java.md) | 繁体中文
+
+**上层标准**: [专案结构](../../core/project-structure.md)
+
+---
+
+## 概述
+
+本文件定义 Java 专案的标准目录结构，特别是使用 Spring Boot 的专案。它遵循以功能为基础的套件组织，促进可维护性和清晰的边界。
+
+## 适用情境
+
+- Spring Boot 应用程式
+- 企业级 Java 应用程式
+- REST 和 GraphQL API
+- 微服务
+- Maven/Gradle 专案
+
+## 目录结构
+
+```
+project-root/
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── com/company/project/
+│   │   │       ├── Application.java          # 进入点
+│   │   │       ├── config/                   # 设定类别
+│   │   │       │   ├── SecurityConfig.java
+│   │   │       │   └── WebConfig.java
+│   │   │       ├── modules/                  # 功能模组
+│   │   │       │   ├── users/
+│   │   │       │   │   ├── User.java         # 实体
+│   │   │       │   │   ├── UserController.java
+│   │   │       │   │   ├── UserService.java
+│   │   │       │   │   ├── UserRepository.java
+│   │   │       │   │   └── dto/
+│   │   │       │   └── products/
+│   │   │       ├── shared/                   # 共用程式码
+│   │   │       │   ├── exception/
+│   │   │       │   └── util/
+│   │   │       └── infrastructure/           # 外部整合
+│   │   └── resources/
+│   │       ├── application.yml
+│   │       └── application-dev.yml
+│   └── test/
+│       └── java/
+│           └── com/company/project/
+├── docs/
+├── pom.xml                    # Maven
+├── build.gradle               # 或 Gradle
+└── README.md
+```
+
+## 命名惯例
+
+| 类型 | 惯例 | 范例 |
+|------|------|------|
+| 档案 | PascalCase.java | `UserService.java` |
+| 套件 | lowercase | `com.company.project.users` |
+| 类别 | PascalCase | `UserService` |
+| 介面 | PascalCase | `UserRepository`（无 I 前缀）|
+| 方法 | camelCase | `createUser()` |
+| 常数 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+
+## 套件组织
+
+### 依功能组织（建议）
+
+```
+com.company.project.modules.users   # 好：功能导向
+com.company.project.modules.products
+
+com.company.project.services        # 避免：技术层导向
+com.company.project.repositories
+```
+
+## Spring Boot 层次
+
+### 实体
+
+```java
+// com/company/project/modules/users/User.java
+@Entity
+@Table(name = "users")
+public class User {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @Column(nullable = false, unique = true)
+    private String email;
+
+    @Column(nullable = false)
+    private String name;
+
+    protected User() {} // For JPA
+
+    public User(String email, String name) {
+        this.email = email;
+        this.name = name;
+    }
+}
+```
+
+### 服务
+
+```java
+// com/company/project/modules/users/UserService.java
+@Service
+@Transactional
+public class UserService {
+
+    private final UserRepository userRepository;
+
+    public UserService(UserRepository userRepository) {
+        this.userRepository = userRepository;
+    }
+
+    public User createUser(CreateUserRequest request) {
+        if (userRepository.existsByEmail(request.email())) {
+            throw new IllegalArgumentException("Email already registered");
+        }
+        User user = new User(request.email(), request.name());
+        return userRepository.save(user);
+    }
+}
+```
+
+### 控制器
+
+```java
+// com/company/project/modules/users/UserController.java
+@RestController
+@RequestMapping("/api/users")
+public class UserController {
+
+    private final UserService userService;
+
+    public UserController(UserService userService) {
+        this.userService = userService;
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public UserResponse createUser(@Valid @RequestBody CreateUserRequest request) {
+        User user = userService.createUser(request);
+        return UserResponse.from(user);
+    }
+}
+```
+
+### DTO
+
+```java
+// com/company/project/modules/users/dto/CreateUserRequest.java
+public record CreateUserRequest(
+    @NotBlank @Email String email,
+    @NotBlank String name
+) {}
+```
+
+## 设定
+
+### application.yml
+
+```yaml
+spring:
+  application:
+    name: myproject
+  datasource:
+    url: jdbc:postgresql://localhost:5432/mydb
+    username: ${DB_USERNAME}
+    password: ${DB_PASSWORD}
+  jpa:
+    hibernate:
+      ddl-auto: validate
+    open-in-view: false
+```
+
+## 最佳实践
+
+1. **建构子注入** - 优先于栏位注入
+2. **依功能组织套件** - 而非技术层
+3. **DTO 分离** - 永远不直接暴露实体
+4. **DTO 使用 Records** - 不可变、简洁
+5. **使用 `@Transactional(readOnly = true)`** - 用于读取操作
+
+## 相关选项
+
+- [Node.js](./nodejs.md) - Node.js 专案结构
+- [Python](./python.md) - Python 专案结构
+- [.NET](./dotnet.md) - .NET/C# 专案结构
+- [Go](./go.md) - Go 专案结构
+
+---
+
+## 授权条款
+
+本文件采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权条款。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/project-structure/nodejs.md

@@ -0,0 +1,185 @@
+---
+source: ../../../../options/project-structure/nodejs.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Node.js 专案结构
+
+> **语言**: [English](../../../../options/project-structure/nodejs.md) | 繁体中文
+
+**上层标准**: [专案结构](../../core/project-structure.md)
+
+---
+
+## 概述
+
+本文件定义 Node.js 和 TypeScript 专案的标准目录结构。它遵循以功能为基础的组织模式，能从小型应用扩展到大型企业系统。
+
+## 适用情境
+
+- Express、Fastify、NestJS 应用程式
+- REST 和 GraphQL API
+- 全端 JavaScript/TypeScript 专案
+- 微服务
+
+## 目录结构
+
+```
+project-root/
+├── src/
+│   ├── index.ts              # 应用程式进入点
+│   ├── app.ts                # Express/Fastify app 设定
+│   ├── config/               # 设定档
+│   │   ├── index.ts
+│   │   ├── database.ts
+│   │   └── env.ts
+│   ├── modules/              # 功能模组（依功能组织）
+│   │   ├── users/
+│   │   │   ├── user.model.ts
+│   │   │   ├── user.service.ts
+│   │   │   ├── user.controller.ts
+│   │   │   ├── user.routes.ts
+│   │   │   ├── user.dto.ts
+│   │   │   ├── user.test.ts
+│   │   │   └── index.ts
+│   │   ├── products/
+│   │   └── orders/
+│   ├── shared/               # 共用工具和类型
+│   │   ├── middleware/
+│   │   ├── utils/
+│   │   └── types/
+│   └── infrastructure/       # 外部服务整合
+│       ├── database/
+│       ├── cache/
+│       └── messaging/
+├── tests/                    # 整合/E2E 测试
+├── scripts/                  # 建置/部署脚本
+├── docs/                     # 文件
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 命名惯例
+
+| 类型 | 惯例 | 范例 |
+|------|------|------|
+| 档案 | kebab-case | `user-profile.service.ts` |
+| 目录 | kebab-case | `order-management/` |
+| 类别 | PascalCase | `UserService` |
+| 函式 | camelCase | `createUser()` |
+| 常数 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 介面 | PascalCase | `UserProfile` |
+
+## 档案后缀
+
+| 后缀 | 用途 |
+|------|------|
+| `.model.ts` | 资料模型/实体 |
+| `.service.ts` | 业务逻辑 |
+| `.controller.ts` | HTTP 处理器 |
+| `.routes.ts` | 路由定义 |
+| `.dto.ts` | 资料传输物件 |
+| `.test.ts` | 测试档案 |
+| `.middleware.ts` | Express/Fastify 中介软体 |
+
+## 模组结构范例
+
+```typescript
+// src/modules/users/index.ts
+export { User } from './user.model';
+export { UserService } from './user.service';
+export { userRoutes } from './user.routes';
+export type { CreateUserDto, UpdateUserDto } from './user.dto';
+
+// 在其他模组中使用
+import { User, UserService } from '@/modules/users';
+```
+
+## 设定
+
+### package.json 脚本
+
+```json
+{
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "ts-node-dev --respawn src/index.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --ext .ts"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## 最佳实践
+
+### 1. 以功能组织
+
+```
+# 好：依功能组织
+src/modules/users/
+src/modules/products/
+src/modules/orders/
+
+# 避免：依技术层组织
+src/models/
+src/services/
+src/controllers/
+```
+
+### 2. Index 档案作为公开 API
+
+```typescript
+// 每个模组只暴露需要的内容
+// src/modules/users/index.ts
+export { UserService } from './user.service';
+export { User } from './user.model';
+// 内部实作保持私有
+```
+
+### 3. 测试与原始码并置
+
+```
+src/modules/users/
+├── user.service.ts
+├── user.service.test.ts  # 单元测试与原始码并置
+├── user.controller.ts
+└── user.controller.test.ts
+```
+
+## 相关选项
+
+- [Python](./python.md) - Python 专案结构
+- [.NET](./dotnet.md) - .NET/C# 专案结构
+- [Java](./java.md) - Java/Spring 专案结构
+- [Go](./go.md) - Go 专案结构
+
+---
+
+## 授权条款
+
+本文件采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权条款。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/project-structure/python.md

@@ -0,0 +1,229 @@
+---
+source: ../../../../options/project-structure/python.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Python 专案结构
+
+> **语言**: [English](../../../../options/project-structure/python.md) | 繁体中文
+
+**上层标准**: [专案结构](../../core/project-structure.md)
+
+---
+
+## 概述
+
+本文件定义使用现代工具（如 Poetry、pytest 和类型提示）的 Python 专案标准目录结构。它遵循 src 布局模式以实现适当的套件隔离。
+
+## 适用情境
+
+- FastAPI、Flask、Django 应用程式
+- REST 和 GraphQL API
+- 资料科学和机器学习专案
+- CLI 应用程式
+- Python 套件/函式库
+
+## 目录结构
+
+```
+project-root/
+├── src/
+│   └── myproject/            # 主套件（套件名称）
+│       ├── __init__.py
+│       ├── main.py           # 应用程式进入点
+│       ├── config/           # 设定
+│       │   ├── __init__.py
+│       │   └── settings.py
+│       ├── modules/          # 功能模组
+│       │   ├── __init__.py
+│       │   ├── users/
+│       │   │   ├── __init__.py
+│       │   │   ├── models.py
+│       │   │   ├── services.py
+│       │   │   ├── routes.py
+│       │   │   └── schemas.py
+│       │   └── products/
+│       ├── shared/           # 共用工具
+│       │   ├── __init__.py
+│       │   ├── exceptions.py
+│       │   └── utils.py
+│       └── infrastructure/   # 外部服务
+│           ├── __init__.py
+│           └── database.py
+├── tests/                    # 测试
+│   ├── __init__.py
+│   ├── conftest.py           # pytest fixtures
+│   ├── unit/
+│   └── integration/
+├── scripts/                  # 工具脚本
+├── docs/                     # 文件
+├── pyproject.toml            # 专案设定
+├── .env.example
+└── README.md
+```
+
+## 命名惯例
+
+| 类型 | 惯例 | 范例 |
+|------|------|------|
+| 档案 | snake_case | `user_service.py` |
+| 目录 | snake_case | `user_management/` |
+| 类别 | PascalCase | `UserService` |
+| 函式 | snake_case | `create_user()` |
+| 常数 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 私有 | _leading_underscore | `_internal_method()` |
+
+## 汇入顺序
+
+```python
+# 标准函式库
+import os
+from typing import Optional, List
+
+# 第三方套件
+import requests
+from fastapi import FastAPI, HTTPException
+
+# 本地模组
+from myproject.modules.users import UserService
+from myproject.shared.utils import format_date
+```
+
+## 模组结构
+
+### 模型
+
+```python
+# src/myproject/modules/users/models.py
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class User:
+    id: str
+    email: str
+    name: str
+    created_at: datetime
+```
+
+### 服务
+
+```python
+# src/myproject/modules/users/services.py
+from typing import Optional
+from .models import User, CreateUserInput
+from .repository import UserRepository
+
+class UserService:
+    def __init__(self, repository: UserRepository):
+        self._repository = repository
+
+    async def create_user(self, input: CreateUserInput) -> User:
+        """建立新使用者。"""
+        existing = await self._repository.find_by_email(input.email)
+        if existing:
+            raise ValueError("Email already registered")
+        return await self._repository.create(input)
+```
+
+### 路由（FastAPI）
+
+```python
+# src/myproject/modules/users/routes.py
+from fastapi import APIRouter, HTTPException, Depends
+from .services import UserService
+from .schemas import UserCreate, UserResponse
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=201)
+async def create_user(
+    user_data: UserCreate,
+    service: UserService = Depends(get_user_service)
+):
+    try:
+        user = await service.create_user(user_data)
+        return user
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+```
+
+## 设定
+
+### pyproject.toml
+
+```toml
+[project]
+name = "myproject"
+version = "1.0.0"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100.0",
+    "uvicorn>=0.23.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+```
+
+## 最佳实践
+
+### 1. 使用 src 布局
+
+```
+# 防止意外汇入未安装的套件
+project/
+├── src/
+│   └── myproject/  # 套件在此
+└── tests/          # 测试汇入已安装的套件
+```
+
+### 2. 处处使用类型提示
+
+```python
+from typing import Optional, List
+
+def get_users(
+    limit: int = 10,
+    offset: int = 0
+) -> List[User]:
+    ...
+```
+
+### 3. __init__.py 作为公开 API
+
+```python
+# 只汇出需要的内容
+from .models import User
+from .services import UserService
+
+__all__ = ["User", "UserService"]
+```
+
+## 相关选项
+
+- [Node.js](./nodejs.md) - Node.js 专案结构
+- [.NET](./dotnet.md) - .NET/C# 专案结构
+- [Java](./java.md) - Java/Spring 专案结构
+- [Go](./go.md) - Go 专案结构
+
+---
+
+## 授权条款
+
+本文件采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权条款。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)