Design on Zata-砸它

领域驱动设计（DDD）分层架构：用领域语言构建复杂系统

Sun, 12 Apr 2026 12:00:00 +0800

什么是领域驱动设计？

领域驱动设计（Domain-Driven Design，DDD） 由 Eric Evans 在 2003 年提出。它的核心思想是：让软件模型与业务模型保持一致——代码中的术语、结构、行为，应该直接反映业务专家的语言。

DDD 不是一套框架，而是一套思想方法，包含两大部分：

战略设计：划分限界上下文（Bounded Context）、定义通用语言（Ubiquitous Language）
战术设计：实体、值对象、聚合、仓储、领域服务、领域事件等构建块

本文聚焦战术设计，以分层架构为核心，展示 DDD 如何在代码中落地。

DDD 四层架构

graph TB
 classDef presentation fill:#e3f2fd,stroke:#1e88e5,color:#000
 classDef application fill:#e8f5e9,stroke:#43a047,color:#000
 classDef domain fill:#fff3e0,stroke:#fb8c00,color:#000
 classDef infrastructure fill:#fce4ec,stroke:#d81b60,color:#000

 subgraph PL [表现层 Presentation Layer]
 REST[REST API / GraphQL]
 CLI[CLI 命令行]
 MQ_IN[消息消费者]
 end

 subgraph AL [应用层 Application Layer]
 AppService[应用服务 Application Service]
 DTO[数据传输对象 DTO]
 EventHandler[领域事件处理器]
 end

 subgraph DL [领域层 Domain Layer ⭐ 核心]
 Entity[实体 Entity]
 ValueObj[值对象 Value Object]
 Aggregate[聚合根 Aggregate Root]
 DomainService[领域服务 Domain Service]
 DomainEvent[领域事件 Domain Event]
 IRepo[仓储接口 IRepository]
 end

 subgraph IL [基础设施层 Infrastructure Layer]
 RepoImpl[仓储实现 Repository Impl]
 ORM[ORM / SQL]
 MQ_OUT[消息发布者]
 Cache[缓存 Redis]
 ExtAPI[外部 API 客户端]
 end

 PL --> AL
 AL --> DL
 IL -->|实现接口| DL
 AL --> IL

 class REST,CLI,MQ_IN presentation
 class AppService,DTO,EventHandler application
 class Entity,ValueObj,Aggregate,DomainService,DomainEvent,IRepo domain
 class RepoImpl,ORM,MQ_OUT,Cache,ExtAPI infrastructure

关键约束：领域层不依赖任何其他层，是整个系统的核心。

战术设计核心概念

1. 实体（Entity）

实体具有唯一标识，通过 ID 区分，即使属性完全相同，两个不同 ID 的实体也是不同的对象。实体的生命周期内状态可以改变。

# domain/model/user.py
from dataclasses import dataclass, field
from uuid import UUID, uuid4
from datetime import datetime


@dataclass
class User:
 """用户实体 - 通过 user_id 唯一标识"""
 username: str
 email: str
 user_id: UUID = field(default_factory=uuid4)
 created_at: datetime = field(default_factory=datetime.utcnow)
 _is_active: bool = field(default=True, repr=False)

 @property
 def is_active(self) -> bool:
 return self._is_active

 def deactivate(self) -> None:
 if not self._is_active:
 raise ValueError("用户已经处于停用状态")
 self._is_active = False

 def change_email(self, new_email: str) -> None:
 if "@" not in new_email:
 raise ValueError(f"无效的邮件地址: {new_email}")
 self.email = new_email

 def __eq__(self, other: object) -> bool:
 if not isinstance(other, User):
 return False
 return self.user_id == other.user_id # 实体相等性基于 ID

 def __hash__(self) -> int:
 return hash(self.user_id)

2. 值对象（Value Object）

值对象没有唯一标识，通过所有属性值来判断相等性，且是不可变的。值对象描述"是什么"，而不是"是哪个"。

# domain/model/money.py
from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True) # frozen=True 确保不可变
class Money:
 """金额值对象 - 金额+货币的组合"""
 amount: Decimal
 currency: str

 def __post_init__(self):
 if self.amount < 0:
 raise ValueError("金额不能为负数")
 if len(self.currency) != 3:
 raise ValueError("货币代码必须是 3 位（如 CNY、USD）")

 def add(self, other: "Money") -> "Money":
 if self.currency != other.currency:
 raise ValueError(f"不能将 {self.currency} 与 {other.currency} 相加")
 return Money(self.amount + other.amount, self.currency)

 def multiply(self, factor: Decimal) -> "Money":
 return Money(self.amount * factor, self.currency)

 def __str__(self) -> str:
 return f"{self.currency} {self.amount:.2f}"


# 值对象的相等性基于值，而不是内存地址
price1 = Money(Decimal("99.00"), "CNY")
price2 = Money(Decimal("99.00"), "CNY")
assert price1 == price2 # True！两个不同对象但值相同


# domain/model/address.py
@dataclass(frozen=True)
class Address:
 """地址值对象"""
 province: str
 city: str
 district: str
 street: str
 postal_code: str

 @property
 def full_address(self) -> str:
 return f"{self.province}{self.city}{self.district}{self.street}"

3. 聚合根（Aggregate Root）

聚合是一组紧密关联的对象的集合，聚合根是这个集合的入口点和守卫者。外部代码只能通过聚合根访问聚合内的对象，聚合根负责维护聚合内的不变性规则（Invariants）。

# domain/model/order.py
from dataclasses import dataclass, field
from decimal import Decimal
from uuid import UUID, uuid4
from datetime import datetime
from domain.model.money import Money
from domain.model.address import Address
from domain.events.order_events import OrderConfirmedEvent, OrderCancelledEvent


@dataclass
class OrderLine:
 """订单行 - 聚合内的实体，只能通过 Order 操作"""
 product_id: UUID
 product_name: str
 quantity: int
 unit_price: Money
 line_id: UUID = field(default_factory=uuid4)

 @property
 def subtotal(self) -> Money:
 return self.unit_price.multiply(Decimal(self.quantity))


@dataclass
class Order:
 """订单聚合根 - 维护订单的所有不变性规则"""
 customer_id: UUID
 shipping_address: Address
 order_id: UUID = field(default_factory=uuid4)
 _lines: list[OrderLine] = field(default_factory=list, repr=False)
 _status: str = field(default="draft", repr=False)
 _domain_events: list = field(default_factory=list, repr=False)
 created_at: datetime = field(default_factory=datetime.utcnow)

 # ---- 业务行为 ----

 def add_item(self, product_id: UUID, name: str, qty: int, price: Money) -> None:
 """添加订单行（聚合内的不变性：每种商品只能有一行）"""
 if any(line.product_id == product_id for line in self._lines):
 raise ValueError(f"商品 {product_id} 已在订单中，请修改数量而非重复添加")
 if qty <= 0:
 raise ValueError("商品数量必须大于 0")
 self._lines.append(OrderLine(product_id, name, qty, price))

 def remove_item(self, product_id: UUID) -> None:
 self._lines = [l for l in self._lines if l.product_id != product_id]

 def confirm(self) -> None:
 """确认订单，触发领域事件"""
 if self._status != "draft":
 raise ValueError(f"只有草稿状态的订单可以确认，当前: {self._status}")
 if not self._lines:
 raise ValueError("订单中没有商品，无法确认")
 self._status = "confirmed"
 # 发布领域事件
 self._domain_events.append(OrderConfirmedEvent(
 order_id=self.order_id,
 customer_id=self.customer_id,
 total_amount=self.total_amount,
 ))

 def cancel(self, reason: str) -> None:
 if self._status in ("cancelled", "shipped"):
 raise ValueError(f"当前状态 {self._status} 无法取消")
 self._status = "cancelled"
 self._domain_events.append(OrderCancelledEvent(
 order_id=self.order_id,
 reason=reason,
 ))

 # ---- 查询属性 ----

 @property
 def total_amount(self) -> Money:
 if not self._lines:
 return Money(Decimal("0"), "CNY")
 result = self._lines[0].subtotal
 for line in self._lines[1:]:
 result = result.add(line.subtotal)
 return result

 @property
 def status(self) -> str:
 return self._status

 @property
 def lines(self) -> list[OrderLine]:
 return list(self._lines) # 返回副本，防止外部修改

 def pop_domain_events(self) -> list:
 """消费领域事件（应用层负责分发）"""
 events = list(self._domain_events)
 self._domain_events.clear()
 return events

4. 仓储（Repository）

仓储提供了一个类似集合的接口来访问聚合根，屏蔽了底层存储细节。接口定义在领域层，实现在基础设施层。

# domain/repositories/order_repository.py （领域层，只有接口）
from abc import ABC, abstractmethod
from uuid import UUID
from domain.model.order import Order


class IOrderRepository(ABC):

 @abstractmethod
 def add(self, order: Order) -> None:
 """将新订单加入仓储"""
 ...

 @abstractmethod
 def get(self, order_id: UUID) -> Order | None:
 """根据 ID 获取订单，不存在返回 None"""
 ...

 @abstractmethod
 def list_by_customer(self, customer_id: UUID) -> list[Order]:
 """获取某客户的所有订单"""
 ...

 @abstractmethod
 def update(self, order: Order) -> None:
 """更新已有订单"""
 ...

# infrastructure/repositories/sql_order_repository.py （基础设施层，具体实现）
from uuid import UUID
from sqlalchemy.orm import Session
from domain.model.order import Order
from domain.repositories.order_repository import IOrderRepository
from infrastructure.orm.order_orm import OrderORM
from infrastructure.mappers.order_mapper import OrderMapper


class SqlOrderRepository(IOrderRepository):

 def __init__(self, session: Session):
 self._session = session

 def add(self, order: Order) -> None:
 orm = OrderMapper.to_orm(order)
 self._session.add(orm)

 def get(self, order_id: UUID) -> Order | None:
 orm = self._session.get(OrderORM, str(order_id))
 return OrderMapper.to_domain(orm) if orm else None

 def list_by_customer(self, customer_id: UUID) -> list[Order]:
 orms = self._session.query(OrderORM).filter_by(
 customer_id=str(customer_id)
 ).all()
 return [OrderMapper.to_domain(orm) for orm in orms]

 def update(self, order: Order) -> None:
 orm = self._session.get(OrderORM, str(order.order_id))
 if not orm:
 raise ValueError(f"订单 {order.order_id} 不存在")
 OrderMapper.update_orm(orm, order)

5. 领域服务（Domain Service）

当某个业务操作跨越多个聚合，或者不自然地归属于某个实体时，应使用领域服务。

# domain/services/pricing_service.py
from decimal import Decimal
from domain.model.money import Money
from domain.model.order import Order


class PricingService:
 """定价领域服务：计算跨聚合的折扣规则（不属于 Order 或 Customer 单独负责）"""

 def calculate_discount(self, order: Order, customer_tier: str) -> Money:
 """根据客户等级计算折扣金额"""
 discount_rates = {
 "bronze": Decimal("0.00"),
 "silver": Decimal("0.05"),
 "gold": Decimal("0.10"),
 "platinum": Decimal("0.15"),
 }
 rate = discount_rates.get(customer_tier, Decimal("0.00"))
 return order.total_amount.multiply(rate)

 def apply_coupon(self, order: Order, coupon_code: str) -> Money:
 """应用优惠券（实际场景中还需查询优惠券仓储）"""
 fixed_coupons = {
 "SAVE20": Money(Decimal("20"), "CNY"),
 "SAVE50": Money(Decimal("50"), "CNY"),
 }
 return fixed_coupons.get(coupon_code, Money(Decimal("0"), "CNY"))

6. 领域事件（Domain Event）

领域事件表示领域中发生了某件重要的事情，是聚合之间解耦通信的核心机制。

# domain/events/order_events.py
from dataclasses import dataclass
from uuid import UUID
from datetime import datetime
from domain.model.money import Money


@dataclass(frozen=True)
class DomainEvent:
 occurred_at: datetime = None

 def __post_init__(self):
 object.__setattr__(self, 'occurred_at', datetime.utcnow())


@dataclass(frozen=True)
class OrderConfirmedEvent(DomainEvent):
 """订单确认后发布，通知库存服务、积分服务、通知服务等"""
 order_id: UUID = None
 customer_id: UUID = None
 total_amount: Money = None


@dataclass(frozen=True)
class OrderCancelledEvent(DomainEvent):
 """订单取消后发布，触发退款流程"""
 order_id: UUID = None
 reason: str = ""

7. 应用服务（Application Service）

应用服务是领域层的编排者，它不包含业务逻辑，只负责：加载聚合、调用领域方法、持久化、分发领域事件。

# application/services/order_application_service.py
from dataclasses import dataclass
from decimal import Decimal
from uuid import UUID
from domain.model.order import Order
from domain.model.money import Money
from domain.model.address import Address
from domain.repositories.order_repository import IOrderRepository
from domain.services.pricing_service import PricingService
from application.event_bus import EventBus


@dataclass
class PlaceOrderCommand:
 customer_id: UUID
 customer_tier: str
 shipping_address: dict
 items: list[dict]
 coupon_code: str | None = None


class OrderApplicationService:
 def __init__(
 self,
 order_repo: IOrderRepository,
 pricing_service: PricingService,
 event_bus: EventBus,
 ):
 self._order_repo = order_repo
 self._pricing = pricing_service
 self._event_bus = event_bus

 def place_order(self, cmd: PlaceOrderCommand) -> UUID:
 # 1. 构建地址值对象
 address = Address(**cmd.shipping_address)

 # 2. 创建订单聚合根
 order = Order(customer_id=cmd.customer_id, shipping_address=address)

 # 3. 添加商品
 for item in cmd.items:
 order.add_item(
 product_id=item["product_id"],
 name=item["name"],
 qty=item["quantity"],
 price=Money(Decimal(str(item["unit_price"])), "CNY"),
 )

 # 4. 应用折扣（领域服务）
 discount = self._pricing.calculate_discount(order, cmd.customer_tier)
 if cmd.coupon_code:
 coupon_discount = self._pricing.apply_coupon(order, cmd.coupon_code)
 discount = discount.add(coupon_discount)

 # 5. 确认订单（触发领域事件）
 order.confirm()

 # 6. 持久化
 self._order_repo.add(order)

 # 7. 分发领域事件（通知其他限界上下文）
 for event in order.pop_domain_events():
 self._event_bus.publish(event)

 return order.order_id

完整项目结构

ecommerce/
├── domain/ # 领域层（纯业务，零外部依赖）
│ ├── model/
│ │ ├── order.py # Order 聚合根 + OrderLine 实体
│ │ ├── user.py # User 实体
│ │ ├── money.py # Money 值对象
│ │ └── address.py # Address 值对象
│ ├── repositories/
│ │ ├── order_repository.py # IOrderRepository 接口
│ │ └── user_repository.py # IUserRepository 接口
│ ├── services/
│ │ └── pricing_service.py # 领域服务
│ └── events/
│ └── order_events.py # 领域事件定义
│
├── application/ # 应用层（编排，不含业务规则）
│ ├── services/
│ │ └── order_application_service.py
│ ├── commands/ # 命令对象（写操作）
│ │ └── place_order_command.py
│ ├── queries/ # 查询对象（读操作，可绕过领域层）
│ │ └── get_order_query.py
│ └── event_bus.py # 领域事件总线接口
│
├── infrastructure/ # 基础设施层（技术实现）
│ ├── repositories/
│ │ └── sql_order_repository.py
│ ├── orm/
│ │ └── order_orm.py # SQLAlchemy ORM 模型
│ ├── mappers/
│ │ └── order_mapper.py # 领域对象 ↔ ORM 模型映射
│ ├── messaging/
│ │ └── rabbitmq_event_bus.py # 领域事件总线实现
│ └── config/
│ └── database.py
│
├── presentation/ # 表现层（HTTP / CLI / MQ）
│ ├── api/
│ │ ├── routers/
│ │ │ └── order_router.py
│ │ └── schemas/ # Pydantic 请求/响应模型
│ │ └── order_schema.py
│ └── cli/
│ └── admin_commands.py
│
└── main.py # 应用入口 + 依赖注入组装

DDD 核心概念速查表

概念	特征	判断标准
实体（Entity）	有唯一 ID，状态可变	问：同样属性的两个对象是"同一个"还是"两个"？如果是"两个"→ 实体
值对象（Value Object）	无 ID，不可变，值相等即相等	问：它描述的是"某物的特征"而不是"某物本身"？→ 值对象
聚合根（Aggregate Root）	一组对象的唯一入口，维护不变性	问：这组对象需要"整体保持一致"吗？→ 聚合
领域服务（Domain Service）	无状态，跨聚合操作	问：这个操作属于哪个实体？如果不属于任何实体 → 领域服务
领域事件（Domain Event）	不可变，描述已发生的事	问：业务上"某件重要的事发生了"，需要通知其他系统？→ 领域事件
仓储（Repository）	集合语义，只处理聚合根	一个聚合根对应一个仓储接口
应用服务（Application Service）	编排，无业务逻辑	只调用领域对象，不写 if/else 业务判断

何时选择 DDD 分层架构？

适合使用 DDD 的场景：

业务规则复杂，存在大量"不变性约束"（如订单状态机）
需要多个团队协作，需要清晰的限界上下文划分
系统需要长期演进，希望业务逻辑不被技术细节污染
与领域专家深度合作，需要共享通用语言

不适合 DDD 的场景：

简单 CRUD 系统（用 MVC 三层就够了）
快速原型验证，后期再演进
团队对 DDD 概念不熟悉且没有时间学习

参考资料

Eric Evans - Domain-Driven Design: Tackling Complexity in the Heart of Software (2003)
Vaughn Vernon - Implementing Domain-Driven Design (2013)
Vaughn Vernon - Domain-Driven Design Distilled (2016)

简洁架构（Clean Architecture）：让业务逻辑永远不依赖框架

Sun, 12 Apr 2026 11:00:00 +0800

什么是简洁架构？

简洁架构（Clean Architecture）由 Robert C. Martin（Uncle Bob）在 2012 年提出，它并非一个新概念，而是对六边形架构、洋葱架构、BCE 架构等多种架构思想的统一与提炼。

核心目标只有一个：让系统中最重要的部分——业务规则（Business Rules）——与框架、数据库、UI 完全解耦，使其可以独立测试、独立替换。

同心圆模型

简洁架构的标志性图示是四个同心圆，从内到外依次是：

 ┌─────────────────────────────────────────┐
 │ Frameworks & Drivers │ ← 最外层：Web框架、DB、UI
 │ ┌─────────────────────────────────┐ │
 │ │ Interface Adapters │ │ ← 控制器、网关、Presenter
 │ │ ┌─────────────────────────┐ │ │
 │ │ │ Application Business │ │ │ ← Use Cases（用例）
 │ │ │ Rules │ │ │
 │ │ │ ┌─────────────────┐ │ │ │
 │ │ │ │ Enterprise │ │ │ │ ← Entities（实体/领域对象）
 │ │ │ │ Business Rules │ │ │ │
 │ │ │ └─────────────────┘ │ │ │
 │ │ └─────────────────────────┘ │ │
 │ └─────────────────────────────────┘ │
 └─────────────────────────────────────────┘

graph LR
 classDef entity fill:#e8f5e9,stroke:#43a047,color:#000
 classDef usecase fill:#e3f2fd,stroke:#1e88e5,color:#000
 classDef adapter fill:#fff3e0,stroke:#fb8c00,color:#000
 classDef framework fill:#fce4ec,stroke:#d81b60,color:#000

 subgraph L4 [Frameworks & Drivers]
 FastAPI[FastAPI / Flask]
 MySQL[(MySQL / PostgreSQL)]
 Redis[(Redis)]
 end

 subgraph L3 [Interface Adapters]
 Controller[Controller 控制器]
 Presenter[Presenter 输出格式化]
 Gateway[Repository Gateway]
 end

 subgraph L2 [Application Business Rules]
 UC1[UseCase: CreateOrder]
 UC2[UseCase: CancelOrder]
 UC3[UseCase: QueryOrder]
 end

 subgraph L1 [Enterprise Business Rules]
 Order[Order 实体]
 OrderItem[OrderItem 值对象]
 IOrderRepo[IOrderRepository 接口]
 end

 FastAPI --> Controller
 Controller --> UC1
 UC1 --> Order
 UC1 --> IOrderRepo
 Gateway -->|实现| IOrderRepo
 MySQL --> Gateway

 class Order,OrderItem,IOrderRepo entity
 class UC1,UC2,UC3 usecase
 class Controller,Presenter,Gateway adapter
 class FastAPI,MySQL,Redis framework

核心原则：依赖规则（The Dependency Rule）

源代码依赖只能从外向内指向。内层对外层一无所知。

这条规则是简洁架构的灵魂：

层级	可以依赖	不可以依赖
Entities（实体）	无任何外部依赖	全部外层
Use Cases（用例）	Entities	Adapters、Frameworks
Adapters（适配器）	Use Cases、Entities	Frameworks（直接耦合）
Frameworks（框架）	全部内层	—

实际含义举例：

Order 实体类里，不能出现 import sqlalchemy
CreateOrderUseCase 里，不能出现 import fastapi
数据库从 MySQL 换成 MongoDB，只需修改最外层的 Repository 实现，业务逻辑零改动

四层详解

第一层：Entities（企业业务规则）

实体封装了最核心、最稳定的业务规则，它们与任何应用无关，只表达"这个领域的事物是什么"。

# entities/order.py
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
from typing import List
from uuid import UUID, uuid4


class OrderStatus(Enum):
 PENDING = "pending"
 CONFIRMED = "confirmed"
 CANCELLED = "cancelled"


@dataclass
class OrderItem:
 product_id: UUID
 product_name: str
 quantity: int
 unit_price: float

 @property
 def subtotal(self) -> float:
 return self.quantity * self.unit_price


@dataclass
class Order:
 customer_id: UUID
 items: List[OrderItem] = field(default_factory=list)
 id: UUID = field(default_factory=uuid4)
 status: OrderStatus = OrderStatus.PENDING
 created_at: datetime = field(default_factory=datetime.utcnow)

 @property
 def total_amount(self) -> float:
 return sum(item.subtotal for item in self.items)

 def confirm(self) -> None:
 if self.status != OrderStatus.PENDING:
 raise ValueError(f"只有 PENDING 状态的订单才能确认，当前状态: {self.status}")
 self.status = OrderStatus.CONFIRMED

 def cancel(self) -> None:
 if self.status == OrderStatus.CANCELLED:
 raise ValueError("订单已经取消")
 self.status = OrderStatus.CANCELLED

注意：这里没有任何 import 涉及框架或数据库。实体是纯 Python 对象，可以独立测试。

第二层：Use Cases（应用业务规则）

用例编排实体的业务行为，代表"系统能做什么"。它通过**接口（抽象）**与外部世界交互，而不直接依赖具体实现。

# use_cases/interfaces.py （定义抽象接口，属于内层）
from abc import ABC, abstractmethod
from uuid import UUID
from entities.order import Order


class IOrderRepository(ABC):
 @abstractmethod
 def save(self, order: Order) -> None: ...

 @abstractmethod
 def find_by_id(self, order_id: UUID) -> Order | None: ...


class IPaymentGateway(ABC):
 @abstractmethod
 def charge(self, customer_id: UUID, amount: float) -> bool: ...


class INotificationService(ABC):
 @abstractmethod
 def send_confirmation(self, order: Order) -> None: ...

# use_cases/create_order.py
from dataclasses import dataclass
from uuid import UUID
from entities.order import Order, OrderItem
from use_cases.interfaces import IOrderRepository, IPaymentGateway, INotificationService


@dataclass
class CreateOrderRequest:
 customer_id: UUID
 items: list[dict] # [{product_id, product_name, quantity, unit_price}]


@dataclass
class CreateOrderResponse:
 order_id: UUID
 total_amount: float
 status: str


class CreateOrderUseCase:
 def __init__(
 self,
 order_repo: IOrderRepository,
 payment_gateway: IPaymentGateway,
 notification_service: INotificationService,
 ):
 self._order_repo = order_repo
 self._payment = payment_gateway
 self._notification = notification_service

 def execute(self, request: CreateOrderRequest) -> CreateOrderResponse:
 # 1. 创建领域对象
 order = Order(customer_id=request.customer_id)
 for item_data in request.items:
 order.items.append(OrderItem(**item_data))

 # 2. 执行支付（通过接口，不关心底层是支付宝还是微信）
 success = self._payment.charge(request.customer_id, order.total_amount)
 if not success:
 raise ValueError("支付失败，请检查账户余额")

 # 3. 确认订单（领域规则在实体内部）
 order.confirm()

 # 4. 持久化
 self._order_repo.save(order)

 # 5. 发送通知
 self._notification.send_confirmation(order)

 return CreateOrderResponse(
 order_id=order.id,
 total_amount=order.total_amount,
 status=order.status.value,
 )

第三层：Interface Adapters（接口适配器）

这一层负责在"用例的数据格式"和"外部世界的数据格式"之间做转换。

# adapters/repositories/sql_order_repository.py
from uuid import UUID
from sqlalchemy.orm import Session
from entities.order import Order, OrderItem, OrderStatus
from use_cases.interfaces import IOrderRepository
from adapters.models import OrderORM, OrderItemORM # ORM 模型定义在此层


class SqlOrderRepository(IOrderRepository):
 """将 IOrderRepository 接口适配到 SQLAlchemy 实现"""

 def __init__(self, session: Session):
 self._session = session

 def save(self, order: Order) -> None:
 orm = OrderORM(
 id=str(order.id),
 customer_id=str(order.customer_id),
 status=order.status.value,
 created_at=order.created_at,
 )
 for item in order.items:
 orm.items.append(OrderItemORM(
 product_id=str(item.product_id),
 product_name=item.product_name,
 quantity=item.quantity,
 unit_price=item.unit_price,
 ))
 self._session.merge(orm)
 self._session.commit()

 def find_by_id(self, order_id: UUID) -> Order | None:
 orm = self._session.get(OrderORM, str(order_id))
 if not orm:
 return None
 return self._orm_to_entity(orm)

 def _orm_to_entity(self, orm: OrderORM) -> Order:
 order = Order(customer_id=UUID(orm.customer_id))
 order.id = UUID(orm.id)
 order.status = OrderStatus(orm.status)
 order.created_at = orm.created_at
 for item_orm in orm.items:
 order.items.append(OrderItem(
 product_id=UUID(item_orm.product_id),
 product_name=item_orm.product_name,
 quantity=item_orm.quantity,
 unit_price=item_orm.unit_price,
 ))
 return order

# adapters/controllers/order_controller.py （FastAPI 路由层）
from fastapi import APIRouter, Depends
from pydantic import BaseModel
from uuid import UUID
from use_cases.create_order import CreateOrderUseCase, CreateOrderRequest
from adapters.dependencies import get_create_order_use_case # 依赖注入工厂

router = APIRouter(prefix="/orders", tags=["orders"])


class CreateOrderHTTPRequest(BaseModel):
 customer_id: UUID
 items: list[dict]


@router.post("/", status_code=201)
def create_order(
 body: CreateOrderHTTPRequest,
 use_case: CreateOrderUseCase = Depends(get_create_order_use_case),
):
 request = CreateOrderRequest(
 customer_id=body.customer_id,
 items=body.items,
 )
 response = use_case.execute(request)
 return {"order_id": str(response.order_id), "total": response.total_amount}

第四层：Frameworks & Drivers（框架与驱动）

最外层是所有技术细节：Web 框架、ORM、消息队列、缓存。这层的代码量最少，主要是"组装"，而非"业务"。

# main.py （应用入口，负责依赖组装）
from fastapi import FastAPI
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from adapters.controllers.order_controller import router
from adapters.repositories.sql_order_repository import SqlOrderRepository
from adapters.gateways.stripe_payment_gateway import StripePaymentGateway
from adapters.services.email_notification_service import EmailNotificationService
from use_cases.create_order import CreateOrderUseCase

app = FastAPI()
app.include_router(router)

engine = create_engine("postgresql://user:pass@localhost/orders_db")
SessionLocal = sessionmaker(bind=engine)

# 依赖注入：在此处将接口绑定到具体实现
def get_create_order_use_case() -> CreateOrderUseCase:
 session = SessionLocal()
 return CreateOrderUseCase(
 order_repo=SqlOrderRepository(session),
 payment_gateway=StripePaymentGateway(api_key="sk_live_..."),
 notification_service=EmailNotificationService(smtp_host="smtp.example.com"),
 )

项目目录结构

my_app/
├── entities/ # 第一层：纯领域对象，零外部依赖
│ ├── order.py
│ └── user.py
│
├── use_cases/ # 第二层：业务用例 + 接口定义
│ ├── interfaces.py # 抽象接口（Repository, Gateway 等）
│ ├── create_order.py
│ └── cancel_order.py
│
├── adapters/ # 第三层：格式转换和具体实现
│ ├── controllers/ # HTTP 控制器（FastAPI/Flask 路由）
│ ├── repositories/ # Repository 具体实现（SQL/MongoDB）
│ ├── gateways/ # 第三方服务网关（支付、短信等）
│ ├── services/ # 其他服务实现（通知、缓存等）
│ └── models.py # ORM 模型定义
│
├── frameworks/ # 第四层：框架配置、应用组装
│ └── dependencies.py # 依赖注入工厂函数
│
├── tests/
│ ├── unit/ # 单元测试：只测 entities 和 use_cases
│ └── integration/ # 集成测试：测 adapters 层
│
└── main.py # 应用入口

如何测试？

简洁架构最大的优势就是可测性。用例层可以通过 Mock 接口进行纯单元测试，无需启动数据库或 HTTP 服务：

# tests/unit/test_create_order.py
from unittest.mock import MagicMock
from uuid import uuid4
from entities.order import Order
from use_cases.create_order import CreateOrderUseCase, CreateOrderRequest


def test_create_order_success():
 # Arrange：Mock 所有外部依赖
 mock_repo = MagicMock()
 mock_payment = MagicMock()
 mock_payment.charge.return_value = True # 支付成功
 mock_notification = MagicMock()

 use_case = CreateOrderUseCase(mock_repo, mock_payment, mock_notification)

 request = CreateOrderRequest(
 customer_id=uuid4(),
 items=[{
 "product_id": uuid4(),
 "product_name": "Python 编程书",
 "quantity": 2,
 "unit_price": 89.0,
 }]
 )

 # Act
 response = use_case.execute(request)

 # Assert：不依赖数据库，测试飞快
 assert response.total_amount == 178.0
 assert response.status == "confirmed"
 mock_repo.save.assert_called_once()
 mock_notification.send_confirmation.assert_called_once()

简洁架构 vs 传统三层架构

对比维度	传统三层（Controller → Service → DAO）	简洁架构
依赖方向	从上往下，Service 依赖 DAO	向内收敛，业务不依赖技术
可测性	Service 难以脱离数据库测试	Use Case 可纯 Mock 测试
替换框架	换 ORM 需改 Service 层	只改最外层 Repository 实现
业务清晰度	业务逻辑散落在 Service 和 DAO 之间	业务逻辑集中在 Entity + Use Case
学习成本	低，上手快	中等，需要理解接口抽象
适用规模	小型项目、CRUD 为主	中大型、业务复杂、长期维护

常见误区

误区 1：实体（Entity）= 数据库表

在简洁架构中，Entity 是领域对象，包含业务规则和行为，不是数据库行的映射。数据库 ORM 模型应放在 Adapters 层。

误区 2：每个项目都要用简洁架构

对于简单的 CRUD 项目，简洁架构反而是过度设计。当业务规则复杂、团队较大、需要长期维护时，它的价值才能充分体现。

误区 3：必须严格分四层

层数可以根据项目规模调整。小项目可以合并 Entities + Use Cases 为一个 domain/ 目录，重要的是依赖方向的原则不能违背。

参考资料

Robert C. Martin - Clean Architecture: A Craftsman’s Guide to Software Structure and Design (2017)
The Clean Architecture - Uncle Bob’s Blog

从脚本到企业级平台：AI Agent 系统"整洁架构"演进与 Python 落地指南

Sun, 12 Apr 2026 10:00:00 +0800

在 AI 应用爆发的今天，写一个大模型对话脚本只需要 50 行代码。但如果你要开发一个企业级的 Agent 管理平台（支持复杂任务编排、多模型无缝切换、RAG 知识库、数十种动态拔插的 Skill 工具），那 50 行脚本很快就会演变成无法维护的"屎山代码"。

痛点极其明显：

大模型 API 换了（比如从 OpenAI 换到 DeepSeek），整个系统要大改。
加一个新工具（Skill），由于和核心逻辑严重耦合，不小心把之前的流式输出改崩了。
系统无法进行单元测试，每次测试都得真金白银地消耗 Token。

为了解决这些问题，结合领域驱动设计 (DDD) 和 Uncle Bob 的整洁架构 (Clean Architecture) 原则，我们设计了一套**“四层模块化单体架构”**。

本文将通过深度图解与真实代码，带你一步步落地这个现代 Agent 平台架构。

一、架构蓝图：Agent 的"数字仿生体"

我们不把系统看作一堆代码的集合，而是将它隐喻为一个**“数字员工”**。以下是系统的全局架构图：

graph TD
 classDef appLayer fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000
 classDef coreLayer fill:#e8f5e9,stroke:#43a047,stroke-width:2px,color:#000
 classDef platLayer fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#000
 classDef infraLayer fill:#fce4ec,stroke:#d81b60,stroke-width:2px,color:#000
 classDef external fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 5 5,color:#000

 User([用户 / 前端 / 定时器]) --> API

 subgraph Layer1 [1. Apps 层: 感官与嘴巴 - 负责请求接入]
 API[api/ RESTful Web API]
 WS[websocket/ 流式对话]
 end

 subgraph Layer2 [2. Core 层: 核心大脑 - 绝对纯洁的业务逻辑]
 UC[use_cases/ 业务编排: execute_task]

 subgraph AgentCore [agent/ 思考与推理]
 Orchestrator[orchestrator.py 调度引擎]
 Planner[planner.py ReAct/CoT 算法]
 Memory[memory.py 记忆摘要]
 end

 Interfaces((shared/interfaces 接口定义))
 end

 subgraph Layer3 [3. Platform 层: 躯干与技能 - 插件化生态]
 Registry[skills/registry.py 技能注册表]
 SkillBase[skills/base.py 技能基类]
 WeatherSkill[skills/weather_skill.py]
 RAG[rag/ 知识检索与切片]
 end

 subgraph Layer4 [4. Infrastructure 层: 物理世界驱动]
 LLM[models/ OpenAI/Qwen 客户端]
 DB[persistence/ MySQL/Redis]
 HTTP[http_clients/ 发请求查天气等]
 end

 subgraph External [外部物理世界]
 ExtLLM[大模型 API]
 ExtWeather[第三方天气 API]
 ExtDB[(物理数据库)]
 end

 API --> UC
 WS --> UC
 UC --> Orchestrator
 Orchestrator --> Planner
 Orchestrator --> Memory
 Orchestrator -.-> |定义标准| Interfaces
 Registry -.-> |实现| Interfaces
 SkillBase -.-> |实现| Interfaces
 WeatherSkill --> HTTP
 RAG --> DB
 LLM -.-> |实现| Interfaces
 DB -.-> |实现| Interfaces
 LLM ==> ExtLLM
 HTTP ==> ExtWeather
 DB ==> ExtDB

 class Layer1,API,WS appLayer;
 class Layer2,UC,AgentCore,Orchestrator,Planner,Memory,Interfaces coreLayer;
 class Layer3,Registry,SkillBase,WeatherSkill,RAG platLayer;
 class Layer4,LLM,DB,HTTP infraLayer;
 class External,ExtLLM,ExtWeather,ExtDB external;

项目目录结构（与四层架构严格对应）：

agent-platform/
│
├── frontend/ # [独立] 前端层：四层架构的消费者，与后端并列存在
│ ├── src/
│ │ ├── pages/ # 页面（对话页、任务历史、技能管理）
│ │ ├── components/ # UI 组件
│ │ └── api/ # 封装对 apps/ 层的 HTTP/WebSocket 调用
│ └── package.json
│
├── apps/ # [第1层] Apps 层：请求接入，最薄的一层
│ ├── api/
│ │ ├── router.py # FastAPI 路由，只做参数校验和调用用例
│ │ └── schemas.py # 请求/响应 Pydantic 模型
│ └── websocket/
│ └── handler.py # WebSocket 流式对话处理器
│
├── core/ # [第2层] Core 层：纯洁的业务大脑，禁止导入外部库
│ ├── agent/
│ │ ├── orchestrator.py # Agent 编排引擎，驱动 ReAct 循环
│ │ ├── planner.py # 思考算法（ReAct / CoT / ToT）
│ │ └── memory.py # 对话记忆与摘要压缩
│ ├── use_cases/
│ │ └── execute_task.py # 业务用例入口：接收请求，返回结果
│ └── shared/
│ └── interfaces.py # 🔑 核心契约：ILLMInterface / ISkill / ISkillRegistry
│
├── platform/ # [第3层] Platform 层：插件生态，实现 Core 的接口
│ ├── skills/
│ │ ├── base.py # 技能基类（对 ISkill 的便捷封装）
│ │ ├── registry.py # 技能注册表（实现 ISkillRegistry）
│ │ ├── weather_skill.py # 天气查询技能
│ │ ├── email_skill.py # 发邮件技能（未来扩展）
│ │ └── code_skill.py # 代码执行技能（未来扩展）
│ └── rag/
│ ├── retriever.py # 向量检索
│ └── chunker.py # 文本切片
│
├── infrastructure/ # [第4层] Infrastructure 层：脏活累活，对接物理世界
│ ├── models/
│ │ ├── openai_client.py # OpenAI 实现（实现 ILLMInterface）
│ │ └── deepseek_client.py # DeepSeek 实现（未来扩展，换这里即可）
│ ├── persistence/
│ │ ├── mysql_repo.py # MySQL 数据访问
│ │ └── redis_cache.py # Redis 缓存
│ └── http_clients/
│ └── weather_api.py # 第三方天气 API 封装
│
├── tests/ # 测试目录（Core 层可纯 Mock 测试，无需消耗 Token）
│ ├── unit/
│ │ └── test_orchestrator.py # 单元测试：Mock LLM 和 Skill
│ └── integration/
│ └── test_weather_flow.py # 集成测试：端到端流程
│
└── main.py # 依赖注入组装入口：将四层粘合成完整系统

架构四大层级剖析（依赖箭头永远向内或靠接口反转）：

层级	职责	禁止事项
Frontend（前端，独立）	渲染 UI、发起 HTTP/WebSocket 请求，只与 Apps 层通信	不得直接调用 Core 或 Platform 的任何逻辑
Apps（请求接入层）	接收 HTTP/WebSocket 请求，参数校验，转发给 Core	不得包含业务逻辑
Core（核心大脑层）	Agent 思考逻辑（ReAct 循环）、业务编排	禁止 `import requests` 或任何外部库
Platform（平台服务层）	技能市场、RAG 知识库，动态注册 Skill	不得直接访问物理数据库
Infrastructure（基础设施层）	调用 OpenAI SDK、查 MySQL、读文件等脏活	不得包含业务逻辑

前端的角色定位： frontend/ 是整个系统的"嘴脸"，但它不属于后端四层中的任何一层。它是架构的消费者，只能通过 apps/ 层暴露的 API/WebSocket 接口与系统交互，对 core/、platform/、infrastructure/ 的存在一无所知。如果项目规模扩大，前端可以直接拆分为独立仓库单独部署，后端四层结构无需任何改动。

二、代码级穿越：以"帮我查一下杭州明天天气"为例

接下来，严格按照目录结构，用 Python 代码走通一笔真实业务流，体会依赖倒置带来的窒息级优雅。

1. 定义防腐接口 `core/shared/interfaces.py`

这是整个系统架构的"契约"，Core 层需要的工具箱全在这里定义。

# core/shared/interfaces.py
from abc import ABC, abstractmethod
from typing import List, Dict, Any

class ILLMInterface(ABC):
 """大模型提供商的抽象接口"""
 @abstractmethod
 def generate(self, prompt: str, tools: List[Dict] = None) -> Dict:
 pass

class ISkill(ABC):
 """所有平台技能的抽象基类"""
 name: str
 description: str

 @abstractmethod
 def execute(self, **kwargs) -> Any:
 pass

class ISkillRegistry(ABC):
 """技能注册表的抽象接口"""
 @abstractmethod
 def get_skill(self, name: str) -> ISkill:
 pass

 @abstractmethod
 def get_all_schemas(self) -> List[Dict]:
 pass

2. 编写核心大脑 `core/agent/orchestrator.py`

这里是 Agent 的思考流，它只依赖刚才定义的接口，与任何具体实现完全解耦。

# core/agent/orchestrator.py
from core.shared.interfaces import ILLMInterface, ISkillRegistry

class AgentOrchestrator:
 """Agent 编排引擎 (纯业务逻辑)"""

 # 依赖注入：在初始化时，只接收接口，不知道底层是谁
 def __init__(self, llm: ILLMInterface, skill_registry: ISkillRegistry):
 self.llm = llm
 self.skill_registry = skill_registry

 def run(self, user_query: str) -> str:
 print(f"[Core] 收到任务: {user_query}")

 # 1. 获取系统目前所有可用的技能说明书
 available_tools = self.skill_registry.get_all_schemas()

 # 2. 让 LLM 思考意图
 print("[Core] 正在调用大脑(LLM)分析意图...")
 llm_response = self.llm.generate(prompt=user_query, tools=available_tools)

 # 3. 解析 LLM 返回结果，判断是否需要调用工具
 if llm_response.get("tool_call"):
 tool_name = llm_response["tool_call"]["name"]
 tool_args = llm_response["tool_call"]["args"]
 print(f"[Core] 大脑决定调用技能: {tool_name}, 参数: {tool_args}")

 # 4. 去平台层获取具体技能并执行
 skill = self.skill_registry.get_skill(tool_name)
 observation = skill.execute(**tool_args)
 print(f"[Core] 技能执行结果: {observation}")

 # 5. 拿着结果进行二次总结
 final_prompt = f"用户问:{user_query}\n工具返回:{observation}\n请给出最终人类可读回答。"
 final_answer = self.llm.generate(prompt=final_prompt)["text"]
 return final_answer

 return llm_response["text"]

# core/use_cases/execute_task.py
from core.agent.orchestrator import AgentOrchestrator

def execute_chat_task(query: str, orchestrator: AgentOrchestrator) -> str:
 """业务用例：执行对话任务"""
 return orchestrator.run(query)

3. 构建平台生态与技能 `platform/skills/`

跳出核心大脑，来到 platform 层，实现具体的技能插件。

# platform/skills/weather_skill.py
from core.shared.interfaces import ISkill
import requests # Platform/Infra 层允许导入外部库

class WeatherSkill(ISkill):
 name = "weather_skill"
 description = "查询指定城市的天气。参数包含 city: 城市名"

 def execute(self, city: str) -> str:
 print(f"[Platform] 正在查询物理世界 {city} 的天气...")
 # 模拟调用外部 HTTP API (严格来说 HTTP 调用也可抽离到 infra 层)
 # response = requests.get(f"http://weather-api.com?city={city}")
 return f"{city}明天晴，25摄氏度，适合出行。"

# platform/skills/registry.py
from core.shared.interfaces import ISkillRegistry, ISkill
from typing import List, Dict
from platform.skills.weather_skill import WeatherSkill

class LocalSkillRegistry(ISkillRegistry):
 """技能注册表的具体实现"""
 def __init__(self):
 self._skills = {
 "weather_skill": WeatherSkill()
 # 未来可以在这里无缝插入 code_skill, search_skill
 }

 def get_skill(self, name: str) -> ISkill:
 return self._skills.get(name)

 def get_all_schemas(self) -> List[Dict]:
 return [{"name": s.name, "description": s.description} for s in self._skills.values()]

4. 接入基础设施 `infrastructure/models/`

老板要求这次用 OpenAI 实现大脑。我们去 infra 搬砖。

# infrastructure/models/openai_client.py
from core.shared.interfaces import ILLMInterface
from typing import List, Dict

class OpenAIClient(ILLMInterface):
 """大模型接口的具体实现"""
 def __init__(self, api_key: str):
 self.api_key = api_key
 # openai.api_key = api_key

 def generate(self, prompt: str, tools: List[Dict] = None) -> Dict:
 # 这里模拟 OpenAI Function Calling 的真实返回结构
 if "天气" in prompt:
 return {
 "text": "",
 "tool_call": {
 "name": "weather_skill",
 "args": {"city": "杭州"}
 }
 }
 return {"text": "这是一个普通的聊天回复"}

5. 大一统：应用入口与依赖注入 `main.py`

这是最外层的框架代码，将灵魂、躯干、基础设施组装成一个完整的生命体。

# main.py (或 apps/api/router.py)
from core.agent.orchestrator import AgentOrchestrator
from core.use_cases.execute_task import execute_chat_task
from platform.skills.registry import LocalSkillRegistry
from infrastructure.models.openai_client import OpenAIClient

# ==========================================
# 依赖注入 (DI) - 组装数字人
# 如果明天换成 Qwen 模型，只需改下面这一行，其他代码一行不动！
# ==========================================
llm_client = OpenAIClient(api_key="sk-xxxx")
skill_registry = LocalSkillRegistry()

# 将外部躯干注入到大脑中
orchestrator = AgentOrchestrator(llm=llm_client, skill_registry=skill_registry)

def mock_websocket_request():
 user_input = "帮我查一下杭州明天的天气"
 print("--- 请求开始 ---")

 # Apps 层将请求交给 Core 层的用例
 final_result = execute_chat_task(user_input, orchestrator)

 print("--- 最终输出给用户 ---")
 print(final_result)

if __name__ == "__main__":
 mock_websocket_request()

三、终端运行效果（日志穿透层级）

运行 main.py，你将清晰地看到请求是如何穿透这四个架构层的：

--- 请求开始 ---
[Core] 收到任务: 帮我查一下杭州明天的天气
[Core] 正在调用大脑(LLM)分析意图...
[Core] 大脑决定调用技能: weather_skill, 参数: {'city': '杭州'}
[Platform] 正在查询物理世界 杭州 的天气...
[Core] 技能执行结果: 杭州明天晴，25摄氏度，适合出行。
--- 最终输出给用户 ---
用户问:帮我查一下杭州明天的天气
工具返回:杭州明天晴，25摄氏度，适合出行。
请给出最终人类可读回答。

四、为什么一定要这样设计？（灵魂三问）

1. Platform 扩展的威力

仔细看 platform/skills/ 目录。这就是你系统的"外挂市场"。当业务需要增加一个"一键发送邮件"的功能时：

你只需要写一个 email_skill.py，实现 ISkill 接口，然后在 registry.py 里注册即可。系统的核心大脑（Core）完全不需要重构，它甚至不需要重新启动，就能在下一次请求中知道并使用这个新工具。

如果配合最新的 MCP (Model Context Protocol)，你甚至可以动态加载全网的开源工具。

2. 抵御大模型迭代的降维打击

今天 OpenAI 是最强的，明天 DeepSeek 放出了更便宜更好的模型。在面条代码里，这意味着重写几千行的 Prompt 和调用逻辑。

在这个架构里，你只需要：

在 infrastructure/models/ 建一个 deepseek_client.py，实现 ILLMInterface
在 main.py 里换一行依赖注入

你的核心 Agent 推理逻辑毫发无损。

3. 坚守"整洁"生命线

在代码审查（Code Review）时，团队必须立下一条死规矩：

绝对不允许 core/ 目录下的任何文件，直接 import platform/ 或 infrastructure/ 目录下的代码。

Core 是系统的心脏，必须保持纯净。这条规矩可以通过 pylint、import-linter 等工具强制执行。

结语

模块化单体结合整洁架构，是目前应对复杂 AI 业务的最佳实践。它既避免了微服务（Microservices）早期带来的分布式运维灾难，又保持了代码的极度解耦。

这不仅是代码结构的胜利，更是软件工程艺术的胜利。

FastAPI 后端架构设计

Tue, 16 Sep 2025 14:48:04 +0800

FastAPI 项目结构化教程

这是一个经过精心设计的、适用于中大型项目的 FastAPI 后端目录结构。它具有良好的模块化、可扩展性和可维护性。

目录结构总览


.
├── app/ \# 主要的应用代码目录
│ ├── **init**.py \# 将 app 目录标记为 Python 包
│ ├── main.py \# FastAPI 应用的入口文件
│ │
│ ├── api/ \# API 路由（endpoints）层
│ │ ├── **init**.py
│ │ └── v1/ \# API 版本 v1
│ │ ├── **init**.py
│ │ ├── api.py \# 聚合 v1 版本的所有路由
│ │ └── endpoints/ \# 存放各个模块的路由文件
│ │ ├── **init**.py
│ │ ├── users.py
│ │ └── items.py
│ │
│ ├── core/ \# 核心逻辑与配置
│ │ ├── **init**.py
│ │ ├── config.py \# 应用配置（环境变量等）
│ │ ├── security.py \# 安全相关（密码哈希、JWT令牌等）
│ │ └── logger.py \# 日志配置与工具
│ │
│ │── services/ # 新增: 业务逻辑层 (工作流)
│ │ ├── __init__.py
│ │ └── chat_agent/ # 例如 （LangGraph Agent）
│ │ ├── __init__.py
│ │ ├── graph.py # 编译后的 Agent (Workflow)
│ │ ├── state.py # AgentState
│ │ ├── nodes.py # 节点函数
│ │ └── tools.py # 工具 (e.g., RAG, DB lookup)
│ │
│ ├── crud/ \# CRUD 数据库操作层
│ │ ├── **init**.py
│ │ ├── base.py \# 可复用的 CRUD 基类
│ │ ├── crud\_user.py \# 针对 User 模型的 CRUD 操作
│ │ └── crud\_item.py \# 针对 Item 模型的 CRUD 操作
│ │
│ ├── db/ \# 数据库相关
│ │ ├── **init**.py
│ │ ├── base.py \# SQLAlchemy 的声明式基类 (DeclarativeBase)
│ │ ├── session.py \# 数据库会话管理
│ │ └── init\_db.py \# (可选) 初始化数据库脚本
│ │
│ ├── models/ \# SQLAlchemy ORM 模型
│ │ ├── **init**.py
│ │ ├── user.py
│ │ └── item.py
│ │
│ ├── schemas/ \# Pydantic 数据模型（用于数据校验与序列化）
│ │ ├── **init**.py
│ │ ├── user.py
│ │ ├── item.py
│ │ └── token.py
│ │
│ └── dependencies/ \# FastAPI 依赖项注入
│ ├── **init**.py
│ └── common.py \# 通用依赖项（如获取DB会话、获取当前用户）
│
├── tests/ \# 测试代码目录
│ ├── **init**.py
│ ├── conftest.py \# Pytest 的 fixtures 和配置
│ └── api/
│ └── v1/
│ ├── test\_users.py
│
├── logs/ \# 日志文件目录 (运行时自动创建)
│ ├── app.log \# 应用主日志文件
│ ├── app.log.1 \# 轮转的历史日志文件
│ └── app.log.2 \# 轮转的历史日志文件
│
├── .env \# 环境变量文件 (不应提交到 git)
├── .gitignore \# Git 忽略文件配置
├── Dockerfile \# Docker 配置文件
├── requirements.txt \# Python 依赖包列表
└── README.md \# 项目说明文档

详细说明

根目录文件

.env: 存储敏感信息和环境变量，例如数据库连接字符串、JWT 密钥等。
.gitignore: 定义了哪些文件或目录不应被 Git 跟踪。
Dockerfile: 用于构建应用的 Docker 镜像，方便容器化部署。
requirements.txt: 列出项目的所有 Python 依赖库，使用 pip install -r requirements.txt 进行安装。
README.md: 项目的说明文件，介绍如何设置、运行和使用该项目。

`app/` 目录：核心应用

这是你所有业务逻辑代码的家。

main.py:
- 作用: FastAPI 应用的入口点。
- 内容: 创建 FastAPI 实例，挂载中间件 (Middleware)，包含来自 app/api/ 的主路由，并可以定义全局的异常处理程序。
api/ 目录: API 层
- 作用: 负责处理 HTTP 请求，定义 API 的路径、参数和响应。这一层应该保持精简，只做请求的接收和响应的返回，具体的业务逻辑和数据库操作应该调用其他模块来完成。
- v1/: 按版本组织 API 是一个非常好的实践，方便未来升级。
- v1/endpoints/: 每个 *.py 文件代表一组相关的 API 路由（例如 users.py 处理所有 /users 相关的请求）。
- v1/api.py: 这个文件导入 endpoints 中的所有路由，并将它们组合成一个单一的 APIRouter，然后这个 APIRouter 会被 main.py 包含进去。这让 API 版本的管理变得非常清晰。
core/ 目录: 核心配置
- 作用: 存放应用的全局配置和核心功能。
- config.py: 使用 Pydantic 的 BaseSettings 读取 .env 文件和环境变量，为整个应用提供一个统一的配置对象。
- security.py: 处理所有与安全相关的功能，如密码的哈希和验证、JWT 令牌的创建和解码。
- logger.py: 日志系统的配置和工具函数，提供统一的日志记录接口，支持不同级别的日志输出、文件轮转和格式化配置。
db/ 目录: 数据库连接与会话
- 作用: 管理数据库的连接和会话。
- session.py: 定义 SQLAlchemy 的 engine 和 SessionLocal（会话工厂）。
- base.py: 包含 declarative_base() 的实例，我们所有的 ORM 模型都将继承自这个基类。这使得 Alembic（数据库迁移工具）能够发现我们的模型。
models/ 目录: 数据库模型层
- 作用: 定义了与数据库表对应的 SQLAlchemy ORM 模型。每个文件对应一个模型（或一组紧密相关的模型）。这些模型描述了数据的结构。
schemas/ 目录: 数据校验层
- 作用: 定义 Pydantic 模型，FastAPI 用它来做数据验证、序列化和文档生成。
- 职责:
  1. 请求体验证: 验证传入的请求体（例如，创建一个新用户时，确保 email 字段是合法的）。
  2. 响应体塑形: 决定从 API 返回哪些字段（例如，从数据库查询出的用户对象可能包含哈希后的密码，但我们绝不应该在 API 响应中返回它）。
- 通常会为每个模型定义多个 Schema，例如 UserCreate, UserUpdate, UserInDB, User。
crud/ 目录: 数据操作层
- 作用: “Create, Read, Update, Delete” 的缩写。这一层封装了所有与数据库的直接交互。
- 职责: 将数据库操作（如 db.add(obj)) 从 API 路由中分离出来。API 路由不应该直接编写 SQLAlchemy 查询语句，而应该调用这里的函数，例如 crud.user.create_user(...)。这使得代码更易于测试和重用。
- base.py: 可以定义一个通用的 CRUDBase 类，包含 get, get_multi, create, update, delete 等通用方法，然后具体的 crud_user.py 只需继承它并添加特定逻辑即可。
dependencies/ 目录: 依赖注入
- 作用: 存放 FastAPI 的依赖项。依赖注入是 FastAPI 的一个核心特性。
- 职责: 创建可重用的依赖项，例如 get_db 用于为每个请求提供一个数据库会话，并在请求结束后关闭它；get_current_user 用于验证 JWT 令牌并返回当前登录的用户。这些依赖项可以在 API 路径操作函数中直接使用。

`tests/` 目录：测试

作用: 存放所有的测试代码。保持测试代码与应用代码分离。
conftest.py: Pytest 的配置文件，用于定义测试范围内的 fixtures（例如，创建一个临时的测试数据库、一个用于发送请求的 TestClient）。
目录结构: 测试目录的结构最好能镜像 app/ 目录的结构，这样可以很容易地找到对应模块的测试。

`logs/` 目录：日志文件

作用: 存储应用运行时产生的日志文件。
自动创建: 该目录由 app/core/logger.py 在首次运行时自动创建，无需手动创建。
文件轮转: 采用日志轮转机制，当主日志文件达到设定大小（如10MB）时，会自动轮转为历史文件，保持最近的5个日志文件。
建议: 在 .gitignore 中添加 logs/ 目录，避免将日志文件提交到版本控制系统。

示例代码

下面是一些关键文件的示例代码，以帮助你更好地理解它们的具体实现。

`app/main.py`

from fastapi import FastAPI
from app.api.v1 import api
from app.core.config import settings

app = FastAPI(
 title=settings.PROJECT_NAME,
 openapi_url=f"{settings.API_V1_STR}/openapi.json"
)

# 包含 v1 版本的 API 路由
app.include_router(api.api_router, prefix=settings.API_V1_STR)

@app.get("/")
def read_root():
 return {"message": "Welcome to this fantastic app!"}

`app/api/v1/api.py`

from fastapi import APIRouter
from app.api.v1.endpoints import users, items

api_router = APIRouter()

# 包含 users 和 items 的路由
api_router.include_router(users.router, prefix="/users", tags=["users"])
api_router.include_router(items.router, prefix="/items", tags=["items"])

`app/api/v1/endpoints/users.py`

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List

from app import crud, models, schemas
from app.dependencies import common

router = APIRouter()

@router.post("/", response_model=schemas.User)
def create_user(
 user: schemas.UserCreate,
 db: Session = Depends(common.get_db)
):
 db_user = crud.user.get_user_by_email(db, email=user.email)
 if db_user:
 raise HTTPException(status_code=400, detail="Email already registered")
 return crud.user.create_user(db=db, user=user)

@router.get("/", response_model=List[schemas.User])
def read_users(
 skip: int = 0,
 limit: int = 100,
 db: Session = Depends(common.get_db)
):
 users = crud.user.get_users(db, skip=skip, limit=limit)
 return users

`app/core/config.py`

from pydantic_settings import BaseSettings
import os

class Settings(BaseSettings):
 PROJECT_NAME: str = "FastAPI Project"
 API_V1_STR: str = "/api/v1"

 # 数据库配置
 #SQLALCHEMY_DATABASE_URI: str = "sqlite:///./test.db"
 SQLALCHEMY_DATABASE_URI: str = os.getenv("DATABASE_URL", "postgresql://user:password@localhost/db")

 # JWT 配置
 SECRET_KEY: str = "a_very_secret_key"
 ALGORITHM: str = "HS256"
 ACCESS_TOKEN_EXPIRE_MINUTES: int = 30

 class Config:
 env_file = ".env"

settings = Settings()

`app/schemas/user.py`

from pydantic import BaseModel, EmailStr
from typing import Optional

# 基础模型
class UserBase(BaseModel):
 email: EmailStr
 full_name: Optional[str] = None
 is_active: bool = True

# 创建时需要的字段 (继承自 Base，并添加 password)
class UserCreate(UserBase):
 password: str

# 更新时需要的字段 (所有字段都可选)
class UserUpdate(UserBase):
 password: Optional[str] = None

# 存储在数据库中的模型 (包含 hashed_password)
class UserInDBBase(UserBase):
 id: int
 hashed_password: str

 class Config:
 from_attributes = True # Pydantic v2 orm_mode for Pydantic v1

# 从 API 返回给用户的模型 (不包含密码)
class User(UserBase):
 id: int
 is_active: bool

 class Config:
 from_attributes = True

`app/crud/crud_user.py`

from sqlalchemy.orm import Session
from app.core.security import get_password_hash
from app import models, schemas

def get_user(db: Session, user_id: int):
 return db.query(models.User).filter(models.User.id == user_id).first()

def get_user_by_email(db: Session, email: str):
 return db.query(models.User).filter(models.User.email == email).first()

def get_users(db: Session, skip: int = 0, limit: int = 100):
 return db.query(models.User).offset(skip).limit(limit).all()

def create_user(db: Session, user: schemas.UserCreate):
 hashed_password = get_password_hash(user.password)
 db_user = models.User(
 email=user.email,
 full_name=user.full_name,
 hashed_password=hashed_password
 )
 db.add(db_user)
 db.commit()
 db.refresh(db_user)
 return db_user

`app/dependencies/common.py`

from sqlalchemy.orm import Session
from app.db.session import SessionLocal

# 依赖项：为每个请求创建一个独立的数据库会话
def get_db():
 db = SessionLocal()
 try:
 yield db
 finally:
 db.close()

`app/core/logger.py`

import logging
import logging.handlers
import os
from pathlib import Path
from app.core.config import settings

def setup_logger(name: str = __name__) -> logging.Logger:
 """
 设置应用日志记录器

 Args:
 name: 日志记录器名称，默认为调用模块的名称

 Returns:
 配置好的日志记录器实例
 """
 logger = logging.getLogger(name)

 # 避免重复配置
 if logger.handlers:
 return logger

 # 设置日志级别
 log_level = getattr(settings, 'LOG_LEVEL', 'INFO')
 logger.setLevel(getattr(logging, log_level.upper()))

 # 创建日志格式
 formatter = logging.Formatter(
 fmt='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
 datefmt='%Y-%m-%d %H:%M:%S'
 )

 # 控制台处理器
 console_handler = logging.StreamHandler()
 console_handler.setFormatter(formatter)
 logger.addHandler(console_handler)

 # 文件处理器（带轮转）
 log_dir = Path("logs")
 log_dir.mkdir(exist_ok=True)

 file_handler = logging.handlers.RotatingFileHandler(
 filename=log_dir / "app.log",
 maxBytes=10 * 1024 * 1024, # 10MB
 backupCount=5,
 encoding='utf-8'
 )
 file_handler.setFormatter(formatter)
 logger.addHandler(file_handler)

 return logger

# 创建默认的应用日志记录器
app_logger = setup_logger("fastapi_app")

def get_logger(name: str = None) -> logging.Logger:
 """
 获取日志记录器实例

 Args:
 name: 日志记录器名称，如果为None则使用默认应用日志记录器

 Returns:
 日志记录器实例
 """
 if name is None:
 return app_logger
 return setup_logger(name)

这个结构为你提供了一个坚实的起点。你可以根据项目的具体需求，在这个基础上进行调整和扩展。

一个标准的软件项目结构

Wed, 23 Jul 2025 22:58:35 +0800

核心结构概览

在深入探讨每个部分之前，这里是一个标准项目结构的高度概括，分为“基础必备”和“推荐包含”两部分。

/my-awesome-project
├── .gitignore # 必备：告诉 Git 忽略哪些文件
├── LICENSE # 必备：项目许可证
├── README.md # 必备：项目介绍和说明
├── package.json # 必备：依赖管理 (示例为 Node.js)
├── src/ # 必备：存放所有源代码
│ └── ...
└── tests/ # 必备：存放所有测试代码
 └── ...

├── .github/ # 推荐：CI/CD 工作流 (例如 GitHub Actions)
├── config/ # 推荐：存放配置文件
├── dist/ # 推荐：存放编译后的输出文件
├── docs/ # 推荐：存放项目文档
└── scripts/ # 推荐：存放自动化脚本

一个标准的软件项目结构，能够帮助团队成员快速理解项目，降低维护成本，并促进协作。虽然不同语言和框架的项目结构有所差异，但一些通用的最佳实践和目录结构是相通的。本文将介绍一个典型的、与语言无关的软件项目结构。

为什么项目结构很重要？

一个良好定义的项目结构可以：

提高可读性：新人可以快速找到他们需要的文件。
促进协作：统一的结构让团队成员更容易协作开发和进行代码审查。
简化维护：当所有东西都在可预测的位置时，调试和添加新功能会更容易。
自动化：清晰的结构便于设置构建、测试和部署的自动化脚本。

顶层文件

项目根目录通常包含一些元数据文件，用于描述项目、配置环境和定义依赖。

README.md：项目的入口。它应该包含项目的简介、如何安装和运行、如何贡献等信息。这是一个项目最重要的文档。
LICENSE：软件许可证文件，例如 MIT、Apache 2.0 或 GPL。它告诉其他人他们可以使用你的代码做什么。
.gitignore：告诉 Git 哪些文件或目录应该被忽略，不纳入版本控制。例如编译产生的文件（build/, dist/）、依赖包（node_modules/）和敏感信息（.env）。
依赖管理文件：
- package.json (Node.js)
- requirements.txt or pyproject.toml (Python)
- pom.xml or build.gradle (Java/Kotlin)
- go.mod (Go)
- Cargo.toml (Rust) 这个文件定义了项目所需的第三方库和依赖项。
CI/CD 配置文件:
- .github/workflows/ (GitHub Actions)
- .gitlab-ci.yml (GitLab CI/CD)
- Jenkinsfile (Jenkins) 这些文件定义了持续集成和持续部署的流程。

核心目录结构

1. `src` 或 `lib` - 源代码

这是项目的心脏，包含了所有的核心业务逻辑。

src (Source): 这个命名最常见。所有你写的源代码都应该放在这里。
lib (Library): 在某些项目中（特别是库项目）会使用 lib。

src 目录内部的组织方式通常有两种：

按层组织 (Layer-based):

src/
├── controllers/ # 或 routes/ - 处理HTTP请求
├── services/ # 业务逻辑
├── models/ # 数据模型或数据库实体
├── repositories/ # 数据访问层
└── utils/ # 通用工具函数

按功能组织 (Feature-based):

src/
├── user/
│ ├── user.controller.ts
│ ├── user.service.ts
│ └── user.model.ts
├── product/
│ ├── product.controller.ts
│ ├── product.service.ts
│ └── product.model.ts
└── auth/
 ├── auth.controller.ts
 └── auth.service.ts

对于大型项目，按功能组织通常更具扩展性。

2. `tests` - 测试代码

测试是保证软件质量的关键。tests 目录存放所有的测试代码。

tests/
├── unit/ # 单元测试，测试单个函数或模块
│ ├── services/
│ └── utils/
├── integration/ # 集成测试，测试多个模块协同工作
└── e2e/ # 端到端测试，模拟真实用户场景

有些项目会将测试文件和源代码文件放在一起，例如 user.service.ts 和 user.service.spec.ts。这两种方式各有优劣，关键是保持一致性。

3. `docs` - 文档

存放项目的所有文档。

API 文档: 使用 Swagger/OpenAPI 规范自动生成，或手动编写。
架构设计: 描述系统架构、组件和数据流。
贡献指南: CONTRIBUTING.md 也可以放在根目录。
用户手册: 如果是提供给最终用户的软件。

4. `dist` 或 `build` - 构建输出

存放编译、打包或压缩后的文件。这些文件是最终部署到生产环境或分发给用户的。这个目录通常会被添加到 .gitignore 中，因为它可以从源代码重新生成。

5. `config` - 配置文件

存放项目的配置文件。一个好的实践是为不同环境（开发、测试、生产）提供不同的配置文件。

config/
├── default.json
├── development.json
├── production.json
└── test.json

注意：永远不要将密码、API 密钥等敏感信息硬编码在代码或配置文件中，并提交到版本库。使用环境变量（如 .env 文件）来管理这些信息。.env 文件应该被添加到 .gitignore 中，但可以提供一个 .env.example 文件作为模板。

6. `scripts` - 脚本

存放用于自动化任务的脚本。

build.sh: 构建项目。
deploy.sh: 部署项目。
db_migration.sh: 数据库迁移。
ci_check.sh: CI/CD 流程中运行的检查。

7. `assets` 或 `public` - 静态资源

对于 Web 应用，这个目录用于存放静态文件，如图片、CSS 和 JavaScript 文件。

8. `examples` - 示例代码

如果你的项目是一个库或框架，提供一个 examples 目录会非常有帮助。它向用户展示了如何使用你的库。

完整的项目结构示例

通用 Web 应用项目结构示例：

my-awesome-project/
├── .github/
│ └── workflows/
│ └── ci.yml
├── config/
│ ├── default.json
│ └── production.json
├── docs/
│ ├── api/
│ └── architecture.md
├── scripts/
│ ├── build.sh
│ └── deploy.sh
├── src/
│ ├── auth/
│ │ ├── auth.controller.js
│ │ └── auth.service.js
│ ├── user/
│ │ ├── user.controller.js
│ │ ├── user.service.js
│ │ └── user.model.js
│ └── app.js
├── tests/
│ ├── integration/
│ │ └── auth.integration.test.js
│ └── unit/
│ └── user.service.test.js
├── .env.example
├── .gitignore
├── LICENSE
├── package.json
└── README.md

通用python应用项目结构示例

my_project/
│
├── my_project/ # 源代码包（Python 包）
│ ├── __init__.py # 使目录成为 Python 包
│ ├── main.py # 应用入口（可选）
│ ├── cli.py # 命令行接口（可选）
│ ├── config.py # 配置文件
│ ├── models/ # 数据模型（如数据库模型）
│ │ └── __init__.py
│ ├── services/ # 业务逻辑
│ │ └── __init__.py
│ ├── utils/ # 工具函数
│ │ └── __init__.py
│ └── tests/ # 单元测试（可选放外面，见下）
│ ├── __init__.py
│ ├── test_models.py
│ └── test_services.py
│
├── tests/ # 推荐：测试放在项目根目录下
│ ├── __init__.py
│ ├── test_main.py
│ └── test_cli.py
│
├── docs/ # 文档
│ └── index.rst
│
├── scripts/ # 部署或辅助脚本
│ └── deploy.sh
│
├── examples/ # 使用示例
│ └── example_usage.py
│
├── .gitignore # Git 忽略文件
├── .python-version # pyenv 使用（可选）
├── pyproject.toml # 推荐：现代 Python 项目配置（替代 setup.py）
├── setup.cfg # 或 setup.py（传统方式）
├── requirements.txt # 依赖列表（开发/生产）
├── requirements-dev.txt # 开发依赖
├── README.md # 项目说明
├── LICENSE # 开源许可证
└── CHANGELOG.md # 版本变更日志（可选）

代码结构和编写规范

📚如何写出易读、易维护的函数：避免深层嵌套与隐式副作用

适合：Python、JavaScript 等支持函数式和过程式编程语言的开发者
目标：提升代码可读性、降低维护成本、减少 bug

一、问题：为什么有些函数“看起来就很累”？

你有没有遇到过这样的代码？

def process_data(data):
 if data:
 for item in data:
 if item.is_valid():
 result = []
 update_result(result, item) # 修改 result 列表
 if len(result) > 0:
 send_notification(result)
 else:
 log_error("Invalid item")
 else:
 return None

这种代码常见问题：

❌ 缩进太多（3层以上）
❌ 没有返回值，却修改了外部变量（副作用）
❌ 逻辑分散，难测试、难复用

我们来一步步优化它。

二、原则一：控制嵌套层级（建议 ≤3 层）

✅ 原则

超过3层的条件或循环嵌套，应通过“提前返回”或“提取函数”来简化。

❌ 反例（嵌套过深）

def check_user(user):
 if user:
 if user.is_active:
 if user.has_permission:
 return True
 else:
 return False
 else:
 return False
 else:
 return False

✅ 改进：使用“守卫语句”（Guard Clauses）

def check_user(user):
 if not user:
 return False
 if not user.is_active:
 return False
 if not user.has_permission:
 return False
 return True

✅ 优点：

缩进浅，逻辑线性
每个条件独立清晰
易于添加日志或错误处理

三、原则二：避免“隐式修改引用”，优先使用“输入 → 输出”模式

❌ 问题：通过引用修改对象（副作用）

def add_item(items, item):
 items.append(item) # ❌ 修改了传入的列表

my_list = ['a']
add_item(my_list, 'b')
print(my_list) # ['a', 'b'] —— 被“偷偷”改了

⚠️ 风险：调用者不知道列表会被修改，容易出 bug。

✅ 改进：返回新值，不修改原对象

def add_item(items, item):
 return items + [item] # ✅ 返回新列表

my_list = ['a']
new_list = add_item(my_list, 'b')
print(my_list) # ['a'] —— 原列表不变
print(new_list) # ['a', 'b'] —— 新列表返回

✅ 优点：

函数是“纯”的（输入相同，输出相同）
易测试、可组合、可缓存
不会意外影响其他代码

💡 提示：对于大对象，可以用 copy 或不可变数据结构（如 Python 的 tuple、frozenset，或使用 dataclasses + frozen=True）

四、原则三：拆分长调用链，保持职责单一

❌ 问题：调用链太深，像“俄罗斯套娃”

def handle_request():
 data = fetch_data()
 processed = process_data(data)
 result = validate_and_save(processed)
 return result

def process_data(data):
 cleaned = clean_data(data)
 enriched = enrich_data(cleaned)
 formatted = format_data(enriched)
 return formatted

虽然结构清晰，但如果每层都复杂，阅读时要“跳来跳去”。

✅ 改进策略：

提取函数，命名清晰

def process_data(data):
 data = clean_data(data)
 data = enrich_data(data)
 data = format_data(data)
 return data

使用注释或文档说明流程

def process_data(data):
 """
 处理流程：
 1. 清洗数据
 2. 补充信息
 3. 格式化输出
 """
 data = clean_data(data)
 data = enrich_data(data)
 data = format_data(data)
 return data

考虑使用流水线（Pipeline）模式

pipeline = [clean_data, enrich_data, format_data]

def process_data(data):
 result = data
 for step in pipeline:
 result = step(result)
 return result

五、综合案例：从“难读”到“清晰”

❌ 原始代码（嵌套深 + 引用修改）

def process_users(users, result):
 if users:
 for user in users:
 if user.active:
 result.append(user.name.upper())
 else:
 result.append("INACTIVE")
 else:
 result.append("NO_USERS")

✅ 重构后：清晰、无副作用、易测试

def process_user(user):
 if not user.active:
 return "INACTIVE"
 return user.name.upper()

def process_users(users):
 if not users:
 return ["NO_USERS"]
 return [process_user(user) for user in users]

✅ 优点：

没有嵌套地狱
不修改外部变量
每个函数职责单一
可单独测试 process_user

六、实用检查清单 ✅

每次写函数时，问自己：

问题	是/否
函数嵌套超过3层了吗？	☐
函数修改了传入的 list/dict 吗？	☐
函数没有返回值，但有“副作用”吗？	☐
调用链超过5层了吗？	☐
能不能给这个函数起个更清晰的名字？	☐

如果任何一个“是”，就考虑重构。

七、额外建议

使用工具自动检测：
- Python: pylint, flake8（配置 max-nested-blocks=3）
- JavaScript: ESLint（max-depth, max-nested-callbacks）
学习函数式编程思想：纯函数、不可变数据、组合优于嵌套
多写单元测试：你会发现“有副作用的函数”最难测！

总结：好函数的三大特征

🟢 浅嵌套：用“提前返回”代替层层 if
🟢 无隐式副作用：优先返回新值，不修改输入
🟢 职责单一：一个函数只做一件事

💬 记住：
代码是写给人看的，顺便让机器执行。

漂亮的reademe文件使用教程

Tue, 10 Jun 2025 16:09:07 +0800

为什么需要一份漂亮的 README？

第一印象： 吸引用户和潜在贡献者的关键。
清晰文档： 帮助他人（以及未来的你）快速理解项目的用途、安装和使用方法。
提升专业性： 一份结构良好、内容详尽的 README 体现了开发者的严谨和专业。
降低沟通成本： 提前回答了用户可能遇到的常见问题。

一份优秀 README 的核心组成部分

下面是一个推荐的 README 结构，你可以根据自己项目的具体情况进行增删。

标题 (#)： 清晰、简洁的项目名称。
Logo (可选)： 一个精心设计的 Logo 能极大地提升项目的品牌感和辨识度。将 Logo 居中放置效果更佳。
一句话简介 (Tagline)： 用一句话精准地概括你的项目是做什么的。

示例：

<p align="center">
 <a href="项目主页链接">
 <img src="image.png" alt="项目Logo" width="80" height="80">
 </a>
</p>

<h1 align="center">项目标题</h1>

<p align="center">
 这里是一句简短、精炼的话，描述你的项目核心功能。
</p>

2. 徽章 (Badges)

徽章是简洁传达项目状态的小图标，通常放在标题下方。它们提供了诸如构建状态、代码覆盖率、开源协议、版本号等元信息。

常用徽章：
- 构建状态 (Build Status): Travis CI, GitHub Actions
- 代码覆盖率 (Code Coverage): Codecov
- 版本号 (Version): NPM, PyPI, NuGet
- 许可证 (License): MIT, Apache 2.0
- 下载量 (Downloads): GitHub, NPM
- 语言 (Language): 项目主要开发语言
如何生成徽章？
- Shields.io 是最流行的徽章生成服务。你可以根据需要定制各种徽章。 示例：

<p align="center">
 <a href="链接"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status"></a>
 <a href="链接"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
 <a href="链接"><img src="https://img.shields.io/npm/v/你的包名" alt="NPM Version"></a>
</p>

3. 项目介绍 (Introduction)

详细介绍你的项目。

它解决了什么问题？ (Why?)
它有什么核心功能和亮点？ (What?)
它的目标用户是谁？ (Who?)

可以配上项目的截图或 GIF 动图，让介绍更生动。

4. 目录 (Table of Contents) (可选)

如果你的 README 很长，一个目录能帮助用户快速导航到感兴趣的部分。

示例 (使用 HTML details 标签创建可折叠目录):

<details>
 <summary>目录</summary>
 <ol>
 <li><a href="#关于项目">关于项目</a></li>
 <li><a href="#快速开始">快速开始</a></li>
 <li><a href="#使用方法">使用方法</a></li>
 <li><a href="#贡献指南">贡献指南</a></li>
 <li><a href="#许可证">许可证</a></li>
 </ol>
</details>

5. 快速开始 (Getting Started / Installation)

这是 README 中最重要的部分之一。提供清晰、分步的安装和设置指南。

先决条件 (Prerequisites): 运行你的项目需要哪些环境或依赖？（例如：Node.js v16+, Python 3.9+）
安装步骤 (Installation):
1. 克隆仓库: git clone https://github.com/your_username/your_project.git
2. 进入目录: cd your_project
3. 安装依赖: npm install 或 pip install -r requirements.txt

使用代码块 (```) 来展示命令，并指明语言类型以获得语法高亮。

示例：

## 快速开始

### 环境要求

* Node.js (>=16.0.0)
* npm

### 安装步骤

1. 克隆本仓库到本地
 ```sh
 git clone https://github.com/your_username/your_project.git
 ```
2. 安装依赖
 ```sh
 npm install
 ```

6. 使用方法 (Usage / Examples)

展示如何使用你的项目。提供清晰的代码示例，并对关键部分加以解释。如果可能，提供一个动态演示（GIF）。

示例：

## 使用方法

下面是一个基础的使用示例：

```javascript
const myLibrary = require('my-library');

const result = myLibrary.doSomething({
 // 配置选项
});

console.log(result);
```
更多高级用法，请参考 [官方文档](链接到你的文档).

7. 功能特性 (Features)

使用列表清晰地展示项目的主要功能。

示例：

## 功能特性

* ✨ **特性一：** 简洁高效的 API 设计。
* 🚀 **特性二：** 闪电般的执行速度。
* 🎨 **特性三：** 高度可定制化的主题。

(使用 Emoji 可以让列表更生动)

8. 贡献指南 (Contributing)

如果你希望这是一个开源项目，并欢迎他人贡献，请提供明确的指南。

说明你欢迎什么样的贡献（Bug 修复、新功能、文档改进等）。
提供贡献流程（Fork -> Create Branch -> Commit -> Pull Request）。
链接到 CONTRIBUTING.md 文件以获取更详细的说明。

示例：

## 贡献指南

我们欢迎任何形式的贡献！请阅读我们的 **[CONTRIBUTING.md](CONTRIBUTING.md)** 文件来了解我们的代码规范和提交流程。

9. 许可证 (License)

明确你的项目使用的开源许可证。这对于使用者和贡献者都至关重要。

示例：

## 许可证

本项目使用 MIT 许可证。详情请见 [LICENSE](LICENSE) 文件。

10. 致谢与联系方式 (Acknowledgments & Contact)

致谢 (Acknowledgments): 感谢那些为你项目提供过帮助的个人、项目或资源。
联系方式 (Contact): 提供你的联系方式，如邮箱或社交媒体链接。

Markdown 美化技巧

代码块语法高亮： 在 ``` 后面添加语言名称，如 javascript, python, sh。

表格 (Tables): 用于展示结构化数据。

| 功能 | 描述 |
| :--- | :--- |
| A | 功能A的详细描述 |
| B | 功能B的详细描述 |

折叠区域 (Collapsible Sections): 使用 HTML 的 <details> 和 <summary> 标签来隐藏长段落或代码块。

<details>
 <summary>点击查看错误日志</summary>
 <pre><code>
 ... 大段的日志内容 ...
 </code></pre>
</details>

引用 (Blockquotes): 使用 > 来突出显示重要说明。
```
> **注意：** 这是一个重要的提示。
```
使用 Emoji： 适当地使用 Emoji (如 ✨, 🚀, 💡, 🐛) 可以让你的 README 更具活力和可读性。

实用工具推荐

README 模板生成器:
- readme.so: 一个非常棒的在线编辑器，可以让你通过点击和填写来生成一个结构完整的 README。
- Make a README: 提供最佳实践指导和模板。
徽章生成:
- Shields.io: 生成各种状态徽章的首选。
GIF 录制工具:
- Windows/macOS: ScreenToGif, LICEcap, Giphy Capture
Markdown 编辑器:
- VS Code: 内置强大的 Markdown 预览功能。
- Typora: 所见即所得的 Markdown 编辑器，非常优雅。

优秀 README 案例学习

没有什么比直接看好的例子更有效了。去看看这些 GitHub 上的项目，学习它们的优点：

希望这份教程能帮助你打造出既漂亮又实用的 README.md！祝你编码愉快！

软件架构设计-培养软件架构师的思维

Wed, 23 Apr 2025 17:30:33 +0800

软件架构图示例

参考知乎 - 亿图

第一部分：软件架构基础

1. 什么是软件架构？

软件开发早期阶段！！！

软件架构设计是一个在软件开发早期阶段进行的关键过程，软件架构是软件系统的高层次结构，定义了系统的组件、它们之间的关系以及指导系统设计和演化的原则。架构关注系统的非功能性需求（如性能、可扩展性、安全性）和功能性需求。

核心目标：
- 满足功能需求
- 确保系统质量（如可维护性、可靠性）
- 平衡开发成本和长期维护成本

2. 软件架构设计的重要性

软件架构设计的重要性主要体现在以下几个方面：

沟通的桥梁：架构为不同的利益相关者（如开发人员、项目经理、客户等）提供了一个共同理解系统的基础，方便沟通和协作。
早期决策：架构设计涉及一系列关键决策，这些决策在项目早期做出，对后续的开发、部署和维护产生深远影响。正确的架构决策可以避免后期昂贵的修改和返工。
质量属性的保障：架构设计直接影响系统的各种质量属性，如性能、安全性、可伸缩性、可靠性、可维护性、可扩展性等。通过合理的架构设计，可以更好地满足这些非功能性需求。
系统演进的基础：良好的架构能够适应需求的变化和技术的发展，支持系统的长期演进和维护。
风险规避：通过架构设计，可以识别潜在的技术风险和挑战，并提前制定应对策略。
指导开发：架构为开发团队提供了清晰的指导和约束，确保各个模块能够有效地集成和协同工作。

3. 架构师的角色

架构师负责：

定义系统结构和技术选型。
平衡业务需求与技术约束。
与开发团队、产品经理等沟通，确保架构落地。
持续优化架构以适应变化。

第二部分：软件架构设计原则

软件架构设计的核心要素通常包括：

组件（Components）：系统中的主要计算单元或数据存储。

连接器（Connectors）：组件之间交互的机制，如函数调用、消息传递、共享数据等。

配置（Configuration）：组件和连接器的特定组织方式，描述了系统的整体结构。

约束（Constraints）：对架构设计选择的限制，可能来自技术、业务或组织等方面。

原理（Principles）：指导设计决策的基本规则和信念。

软件架构设计的核心原则包括：

关注点分离 (Separation of Concerns): 将系统的不同功能或职责划分到不同的模块或组件中，降低耦合度。

高内聚低耦合 (High Cohesion, Low Coupling): 模块内部的功能应该紧密相关（高内聚），模块之间的依赖关系应该尽可能少（低耦合）。

单一职责原则 (Single Responsibility Principle): 每个模块或组件应该只负责一项特定的功能。

抽象 (Abstraction): 隐藏底层的复杂实现细节，提供简洁易懂的接口。

模块化 (Modularity): 将系统划分为独立的、可替换的模块，便于开发、测试和维护。

可扩展性 (Scalability): 系统应能够方便地进行横向或纵向扩展，以应对不断增长的用户量和数据量。

可测试性 (Testability): 架构设计应便于对各个组件和整个系统进行测试。

可维护性 (Maintainability): 清晰、文档化的架构使得系统更容易被理解、修改和维护。

安全性 (Security): 从架构层面考虑系统的安全需求，构建安全的系统。

合适性原则 (Suitability): 架构设计应根据项目的具体需求、资源和环境选择最合适的方案，而非盲目追求最新或最复杂的技术。

简单性原则 (Simplicity): 在满足需求的前提下，应尽量保持架构的简单性，避免过度设计。

演化性原则 (Evolution): 架构应该能够适应未来的变化和发展，支持逐步演进。

1. SOLID 原则

SOLID 是面向对象设计的五大原则，同样适用于架构设计：

单一职责原则（SRP）：一个模块或类只负责一个功能。
开闭原则（OCP）：对扩展开放，对修改关闭。
里氏替换原则（LSP）：子类可以替换父类而不影响系统行为。
接口隔离原则（ISP）：客户端不应被迫依赖不需要的接口。
依赖倒置原则（DIP）：高层模块不应依赖低层模块，二者都应依赖抽象。

2. 其他关键原则

KISS（Keep It Simple, Stupid）：保持设计简单，避免不必要的复杂性。
DRY（Don’t Repeat Yourself）：避免代码和设计的重复。
YAGNI（You Aren’t Gonna Need It）：只实现当前需求的功能，避免过度设计。
关注点分离（Separation of Concerns）：将系统划分为独立的功能模块。

第三部分：常见架构模式

1. 分层架构（Layered Architecture）

定义：将系统分为多个层次（如表示层、业务逻辑层、数据访问层），每层负责特定功能。
优点：结构清晰，易于维护和测试。
缺点：可能导致性能瓶颈，扩展性受限。
适用场景：传统企业应用、Web 应用。

示例：

表示层（UI） -> 业务逻辑层 -> 数据访问层 -> 数据库

2. 微服务架构（Microservices Architecture）

定义：将系统拆分为小型、独立的服务，每个服务专注于单一功能，通过 API 通信。
优点：高扩展性、独立部署、团队自治。
缺点：分布式系统复杂性、部署和监控成本高。
适用场景：大型分布式系统、快速迭代的产品。
示例：Netflix、Amazon 的服务架构。

3. 事件驱动架构（Event-Driven Architecture）

定义：组件通过事件（消息）异步通信，事件生产者与消费者解耦。
优点：高响应性、松耦合、易于扩展。
缺点：事件追踪和调试复杂。
适用场景：实时处理系统、物联网。
示例：Kafka 或 RabbitMQ 驱动的系统。

4. 领域驱动设计（DDD, Domain-Driven Design）

定义：以业务领域为核心，设计模型和架构，强调领域模型的清晰表达。
优点：贴近业务需求，易于维护。
缺点：学习曲线陡峭，初期投入高。
适用场景：复杂业务系统。

5. 其他模式

模型-视图-控制器（MVC（Model-View-Controller）：分离数据、界面和控制逻辑，常见于 Web 开发。
CQRS（Command Query Responsibility Segregation）：读写分离，优化性能和扩展性。
Serverless 架构：基于云函数，按需运行，降低运维成本。
管道-过滤器架构 (Pipe and Filter Architecture): 将数据处理过程分解为一系列独立的过滤器，数据通过管道在过滤器之间流动。

第四部分：架构设计流程

1. 需求分析

功能需求：明确系统需要实现的功能。
非功能需求：性能、可靠性、可扩展性、安全性等。
约束条件：预算、技术栈、团队能力等。

2. 系统分解

将系统划分为模块或服务。
使用 UML 图（如类图、序列图）或 C4 模型描述系统结构。
定义模块间的接口和通信方式。

3. 技术选型

编程语言：根据团队经验和项目需求选择（如 Java、Python、Go）。
框架：选择合适的框架（如 Spring、Django）。
数据库：关系型（MySQL）还是非关系型（MongoDB）？
基础设施：云服务（AWS、Azure）还是本地部署？

4. 架构验证

原型验证：开发最小可行原型（MVP）测试架构可行性。
性能测试：模拟高负载场景，验证系统性能。
安全评估：检查潜在安全漏洞。

5. 文档化

编写架构设计文档，包含：
- 系统概述
- 架构图（C4 模型、UML 图）
- 技术选型理由
- 模块职责和接口定义
- 部署和维护指南

第五部分：工具与技术

1. 建模工具

UML 工具：Enterprise Architect、StarUML。
C4 模型工具：Structurizr、Draw.io。
流程图工具：Lucidchart、Visio。

2. 架构描述语言

Archimate：企业架构建模语言。
ADL（Architecture Description Language）：用于形式化描述架构。

3. 部署与监控

容器化：Docker、Kubernetes。
CI/CD：Jenkins、GitHub Actions。
监控：Prometheus、Grafana。

第六部分：案例分析

案例：设计一个电商平台架构

需求

支持用户注册、商品浏览、订单处理、支付。
高并发（双11促销）。
可扩展以支持新功能（如推荐系统）。

架构设计

模式：微服务架构 + 事件驱动。
服务拆分：
- 用户服务：管理用户注册、登录。
- 商品服务：商品目录、库存管理。
- 订单服务：订单创建、状态管理。
- 支付服务：对接支付网关。
- 推荐服务：个性化推荐。
技术栈：
- 后端：Spring Boot（Java）。
- 数据库：MySQL（订单、用户）、MongoDB（商品目录）。
- 消息队列：Kafka（异步事件处理）。
- 缓存：Redis（高频数据）。
- 部署：Kubernetes + AWS。

架构图（C4 模型简化版）：

用户 -> API 网关 -> [用户服务, 商品服务, 订单服务, 支付服务]
订单服务 -> Kafka -> 推荐服务
所有服务 -> MySQL/MongoDB/Redis

验证

性能测试：模拟 10 万并发用户，确保响应时间 < 200ms。
安全：使用 OAuth2 认证，加密支付数据。

第七部分：常见挑战与解决方案

1. 可扩展性

问题：系统无法应对用户增长。
解决方案：使用微服务、分布式数据库、负载均衡。

2. 性能瓶颈

问题：响应时间过长。
解决方案：引入缓存（Redis）、CDN，优化数据库查询。

3. 维护复杂性

问题：代码和架构过于复杂。
解决方案：遵循 KISS 和 DRY 原则，定期重构。

4. 分布式系统一致性

问题：数据一致性难以保证。
解决方案：使用分布式事务（如 Saga 模式）或最终一致性。

第八部分：学习资源与进阶

1. 推荐书籍

《软件架构模式》（Mark Richards）
《领域驱动设计》（Eric Evans）
《微服务架构设计模式》（Chris Richardson）

2. 在线课程

Coursera：软件架构与设计
Udemy：微服务架构实战

3. 实践建议

参与开源项目，学习真实架构。
设计小型项目（如博客系统、聊天应用）并优化架构。
关注行业案例（如 Netflix、Uber 的架构分享）。

总结

软件架构设计是一门结合技术和业务的艺术。通过掌握架构原则、模式和流程，开发者可以设计出满足需求、易于维护的系统。持续学习和实践是成为优秀架构师的关键。

作图参考

Tue, 25 Mar 2025 11:00:07 +0800

Development Plan

文档书写参考

使用ai工具绘制原型图html并导入figma

Mon, 10 Mar 2025 11:07:28 +0800

数据流图

Mon, 24 Feb 2025 00:00:00 +0000

数据流图

类图

Thu, 20 Feb 2025 00:00:00 +0000

类图

类图的概念笔记

1. 什么是类图？

类图是 UML（统一建模语言）中最常用的一种静态结构图。
作用：展示系统中类的结构、属性、方法以及类与类之间的关系。
应用场景：软件设计、系统建模，帮助开发者理解和规划代码结构。

2. 类的基本组成

一个类通常用一个矩形框表示，分为三部分：

顶部：类名
- 写类的名称（通常首字母大写）。
- 如果是抽象类，类名用斜体表示。
中间：属性
- 表示类的特性或数据（成员变量）。
- 格式：[可见性] 属性名 : 类型 [默认值]
  - 可见性：+（public）、-（private）、#（protected）、~（package）。
  - 示例：-age : int = 18
底部：方法（操作）
- 表示类的行为或功能（成员函数）。
- 格式：[可见性] 方法名(参数) : 返回类型
  - 示例：+getAge() : int

3. 类与类之间的关系

来源：https://juejin.cn/post/6844903893327937550

类图的核心是描述类之间的关系，常见的有以下几种：

继承关系（Generalization/extends）

继承关系也叫泛化关系，指的是一个类（称为子类、子接口）继承另外的一个类（称为父类、父接口）的功能，并可以增加它自己的新功能的能力，继承是类与类或者接口与接口之间最常见的关系。继承用实线空心箭头表示，由子类指向父类。下面写两个子类，Fish和Cat分别继承自Animal。

实现关系（implements）

指的是一个class类实现interface接口（可以是多个）的功能；实现是类与接口之间最常见的关系；在Java中此类关系通过关键字implements明确标识，在iOS中我将其理解成代理的实现。写一个洋娃娃类Doll，该类遵循了ToyAction协议，实现了玩具移动的方法。

依赖关系（Dependency）

可以简单的理解，就是一个类A使用到了另一个类B，而这种使用关系是具有偶然性的、、临时性的、非常弱的，但是B类的变化会影响到A；比如某人要过河，需要借用一条船，此时人与船之间的关系就是依赖；表现在代码层面，为类B作为参数被类A在某个method方法中使用。在我们的上述代码中Cat的playToy方法中参数引用了Doll，因此他们是依赖关系。

关联关系（Association）

他体现的是两个类、或者类与接口之间语义级别的一种强依赖关系，比如我和我的朋友；这种关系比依赖更强、不存在依赖关系的偶然性、关系也不是临时性的，一般是长期性的，而且双方的关系一般是平等的、关联可以是单向、双向的；表现在代码层面，为被关联类B以类属性的形式出现在关联类A中，也可能是关联类A引用了一个类型为被关联类B的全局变量；写一个Person类，他拥有一个宠物猫，他们之间的关系是关联。

聚合关系（Aggregation）聚合是关联关系的一种特例，他体现的是整体与部分、拥有的关系，即has-a的关系，此时整体与部分之间是可分离的，他们可以具有各自的生命周期，部分可以属于多个整体对象，也可以为多个整体对象共享；比如计算机与CPU、公司与员工的关系等；表现在代码层面，和关联关系是一致的，只能从语义级别来区分；

组合关系（Composition）组合也是关联关系的一种特例，他体现的是一种contains-a的关系，这种关系比聚合更强，也称为强聚合；他同样体现整体与部分间的关系，但此时整体与部分是不可分的，整体的生命周期结束也就意味着部分的生命周期结束；比如你和你的大脑；表现在代码层面，和关联关系是一致的，只能从语义级别来区分；上述代码中的Person拥有Head，并且这个整体和部分是不可分割的。

最后来看看这个例子中的整体关系：

其实理解了之后我们发现还是很简单的，学会了之后就可以投入实践中了，举一个简单第三方库的类图例子，下图是Masonry的类图整理，可以看到项目结构很清晰的展示了出来。

4. 类图的符号速查

矩形框：类
实线：关联
空心菱形+实线：聚合
实心菱形+实线：组合
空心三角+实线：继承
空心三角+虚线：实现
虚线箭头：依赖

Design on Zata-砸它

领域驱动设计（DDD）分层架构：用领域语言构建复杂系统

什么是领域驱动设计？

DDD 四层架构

战术设计核心概念

1. 实体（Entity）

2. 值对象（Value Object）

3. 聚合根（Aggregate Root）

4. 仓储（Repository）

5. 领域服务（Domain Service）

6. 领域事件（Domain Event）

7. 应用服务（Application Service）

完整项目结构

DDD 核心概念速查表

何时选择 DDD 分层架构？

参考资料

简洁架构（Clean Architecture）：让业务逻辑永远不依赖框架

什么是简洁架构？

同心圆模型

核心原则：依赖规则（The Dependency Rule）

四层详解

第一层：Entities（企业业务规则）

第二层：Use Cases（应用业务规则）

第三层：Interface Adapters（接口适配器）

第四层：Frameworks & Drivers（框架与驱动）

项目目录结构

如何测试？

简洁架构 vs 传统三层架构

常见误区

参考资料

从脚本到企业级平台：AI Agent 系统"整洁架构"演进与 Python 落地指南

一、架构蓝图：Agent 的"数字仿生体"

二、代码级穿越：以"帮我查一下杭州明天天气"为例

1. 定义防腐接口 core/shared/interfaces.py

2. 编写核心大脑 core/agent/orchestrator.py

3. 构建平台生态与技能 platform/skills/

4. 接入基础设施 infrastructure/models/

5. 大一统：应用入口与依赖注入 main.py

三、终端运行效果（日志穿透层级）

四、为什么一定要这样设计？（灵魂三问）

1. Platform 扩展的威力

2. 抵御大模型迭代的降维打击

3. 坚守"整洁"生命线

结语

FastAPI 后端架构设计

FastAPI 项目结构化教程

目录结构总览

详细说明

根目录文件

app/ 目录：核心应用

tests/ 目录：测试

logs/ 目录：日志文件

示例代码

app/main.py

app/api/v1/api.py

app/api/v1/endpoints/users.py

app/core/config.py

app/schemas/user.py

app/crud/crud_user.py

app/dependencies/common.py

app/core/logger.py

一个标准的软件项目结构

目录

核心结构概览

为什么项目结构很重要？

顶层文件

核心目录结构

1. src 或 lib - 源代码

2. tests - 测试代码

3. docs - 文档

4. dist 或 build - 构建输出

5. config - 配置文件

6. scripts - 脚本

7. assets 或 public - 静态资源

8. examples - 示例代码

完整的项目结构示例

通用 Web 应用项目结构示例：

通用python应用项目结构示例

代码结构和编写规范

📚如何写出易读、易维护的函数：避免深层嵌套与隐式副作用

1. 定义防腐接口 `core/shared/interfaces.py`

2. 编写核心大脑 `core/agent/orchestrator.py`

3. 构建平台生态与技能 `platform/skills/`

4. 接入基础设施 `infrastructure/models/`

5. 大一统：应用入口与依赖注入 `main.py`

`app/` 目录：核心应用

`tests/` 目录：测试

`logs/` 目录：日志文件

`app/main.py`

`app/api/v1/api.py`

`app/api/v1/endpoints/users.py`

`app/core/config.py`

`app/schemas/user.py`

`app/crud/crud_user.py`

`app/dependencies/common.py`

`app/core/logger.py`

1. `src` 或 `lib` - 源代码

2. `tests` - 测试代码

3. `docs` - 文档

4. `dist` 或 `build` - 构建输出

5. `config` - 配置文件

6. `scripts` - 脚本

7. `assets` 或 `public` - 静态资源

8. `examples` - 示例代码