Exavatar | Michaell Alavedra

本文档详细介绍了 Exavatar 的架构、领域设计和技术实现。Exavatar 是一款动态头像生成渲染引擎及 API。该解决方案解决了 Web 和移动应用开发中经常遇到的问题：当最终用户未提供个人资料图片时，默认图片或 placeholders 的管理问题。

业务实用性与工作流

本项目解决的核心问题是用户界面中临时视觉身份的缺失，这通常需要每个开发团队在客户端实现冗余的首字母生成逻辑或图片条件加载逻辑。

Exavatar 将这一责任完全转移到了服务端。该工具作为一个 REST API，通过 URL 中的结构化参数，立即返回头像——要么服务于预定义集合中的静态资源（例如 WEBP/PNG 格式的动物或角色），要么利用用户的首字母和彩色背景即时生成 SVG。

应用的主要工作流如下运行：

接收请求： 客户端向 API 发起带有特定参数（set, id, size, format, color, text）的 HTTP GET 请求。
领域评估： 应用核心解析 URL 参数以实例化主实体 (Avatar)。如果提供了 text 参数，应用将确定必须编译并返回动态生成的 SVG。否则，它将验证大小、集合和格式属性以构建有效的文件路径。
仓库解析： 根据运行环境（开发 vs. 生产），应用层将图片的物理加载委托给相应的基础设施适配器（本地或基于网络）。
响应： 服务端返回图片的二进制数据或带有正确 HTTP 标头和缓存配置的 SVG 字符串，从而最小化后续请求中的计算开销。

深入分析：架构与数据建模

源码设计（主要位于 src/core/）是对 领域驱动设计 (DDD) 的严格实现，在 六边形架构 (Ports and Adapters) 模式下构建。采用这一技术决策绝非偶然；它的引入是为了将业务逻辑和生成规则与呈现层 (Astro) 及基础设施层（网络/文件系统）完全隔离。

整体架构

职责分离保证了核心 (domain) 没有任何外部依赖，使代码天然具备可测试性和可扩展性。

flowchart TD
    subgraph Presentacion ["呈现层 (Astro / API Routes)"]
        API["路由 /api/avatar"]
    end

    subgraph CapaAplicacion ["应用层"]
        AS["AvatarService"]
    end

    subgraph CapaDominio ["领域层 (核心)"]
        A["Avatar : 实体"]
        VO1["AvatarSize : 值对象"]
        VO2["AvatarColor : 值对象"]
        VO3["AvatarId : 值对象"]
        VO4["AvatarSet : 值对象"]
        VO5["AvatarText : 值对象"]
        Repo["AvatarRepository : 端口"]

        A --> VO1
        A --> VO2
        A --> VO3
        A --> VO4
        A --> VO5
    end

    subgraph CapaInfraestructura ["基础设施层 (适配器)"]
        LRepo["LocalAvatarRepository"]
        GRepo["GitHubAvatarRepository"]
    end

    API --> AS
    AS --> Repo
    AS --> A
    LRepo -.-> Repo
    GRepo -.-> Repo

数据建模与业务逻辑

业务逻辑存在于 值对象 (Value Objects) 和 聚合根 (Aggregate Root) 实体 (Avatar) 中。它们确保应用永远不会处理无效状态。

Avatar 实体： 协调验证与转换。暴露 needBuild() 方法，通过评估值对象 AvatarText 是否包含有效值，决定执行流（读取静态文件 vs. 生成 SVG）。
值对象 (Value Objects)：
- AvatarSize：验证允许的限制和分辨率（例如限制在 16px 到 512px 之间）。
- AvatarColor：规范化十六进制值并计算次要逻辑（例如基于背景色亮度自动调整 SVG 文本对比度）。
- AvatarId、AvatarSet 与 AvatarFormat：确保请求的标识符属于有效集合，且输出格式得到支持（webp、png、svg）。

classDiagram
    class Avatar {
        +AvatarSet set
        +AvatarId id
        +AvatarSize size
        +AvatarFormat format
        +AvatarColor color
        +AvatarText text
        +String filepath
        +String filename
        +fromUrl(URL url) Avatar$
        +needBuild() boolean
    }
    class AvatarService {
        -AvatarRepository repository
        +generate(URL url) Promise<AvatarResult>
    }
    class AvatarRepository {
        <<interface>>
        +load(Avatar avatar) Promise<AvatarResult>
    }

    AvatarService --> AvatarRepository : 使用
    AvatarService ..> Avatar : 构建

编排服务 AvatarService 通过构造函数应用依赖注入。在运行时，系统注入 GitHubAvatarRepository 以在生产仓库中查找静态资源，或注入 LocalAvatarRepository 以在开发期间从本地磁盘读取。

技术栈

工具链的选择完全基于性能和类型控制。

技术	在架构中的角色
Astro	呈现层与服务端渲染 (SSR) 框架。管理 API 路由，并通过 Edge Network 交付快速响应，无需在客户端注入 JavaScript。
TypeScript	主要语言。对领域层建模至关重要，确保端口与适配器之间接口的严格契约。
Vitest	单元测试环境。允许完全隔离地测试领域层和 `AvatarService`，注入模拟仓库 (mocks)。
BiomeJS	唯一的静态分析工具 (linter) 与格式化工具。配置为使用 tab 缩进和单引号，完全替代 Prettier 和 ESLint 以获得更快的执行速度。
Vercel	部署基础设施。通过 `@astrojs/vercel` 使用 Serverless/Edge Functions 进行处理和生成的图片的全局 CDN 交付。

在现代 JavaScript 环境中对 DDD 原则、高级静态类型和纯六边形架构的严谨整合，带来了一个在渲染引擎与文件分发基础设施之间完全解耦的系统。这种抽象允许在无需修改领域逻辑的情况下扩展、更换托管平台或添加新的算法生成格式。

业务实用性与工作流

深入分析：架构与数据建模

整体架构

数据建模与业务逻辑

技术栈

一起合作