建筑愿景

指导原则

架构基于*关注点分离*的原则:

  • 内容 : 结构丰富的 AsciiDoc 文件,带有丰富的元数据

  • Presentation : 可重用的 Thymeleaf 模板

  • 数据 : 由 JBake 自动从 AsciiDoc 属性提取的模型

  • 样式 : Bootstrap 5 用于视觉一致性

战略选择:AsciiDoc 用于投资组合

为什么 AsciiDoc ?

标准 �优势

一致性

与博客文章相同的格式

元数据

结构化和可扩展的属性 (project-*)

可维护性

简单文本编辑,可由 Git 版本控制

灵活性

可以包含丰富内容 (表格, 代码, 图片)

模板

JBake 自动提取 Thymeleaf 的属性

数据模型

每个投资组合项目都是一个 AsciiDoc 文档,包含:

  • 表头元数据 : 结构化信息(客户、时长、技术等)

  • 文档正文 : 叙事描述, 挑战, 解决方案, 结果

  • 自定义属性 : 前缀`project-*`用于自动提取

Diagram

详细用例

UC1 : 添加一个元素到投资组合

额定通量

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ]

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "编辑器
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "编辑器
文本" as editor
participant "文件\nAsciiDoc" as file
participant "JBake
引擎" as jbake
participant "站点
静态" as site

dev -> editor : Créer nouveau fichier
activate editor
editor -> file : portfolio/nouveau-projet.adoc
activate file

dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*)
dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions)
dev -> editor : Ajouter images dans assets/img/portfolio/

editor -> file : Sauvegarder
deactivate editor

dev -> jbake : Lancer build (jbake -b)
activate jbake
jbake -> file : Lire et parser
jbake -> jbake : Extraire métadonnées
jbake -> jbake : Convertir AsciiDoc → HTML
jbake -> jbake : Appliquer template project.html
jbake -> jbake : Ajouter à la liste portfolio.html
jbake -> site : Générer pages statiques
deactivate jbake

dev -> site : Vérifier résultat
activate site
site --> dev : Afficher projet
deactivate site
@enduml

要创建的文件模板

开发者创建`content/portfolio/nom-projet.adoc`具有标准化的结构:

  • 包含所有必需属性的标题

  • 标准化部分(背景、挑战、解决方案、结果)

  • 图像的一致命名

验证点

  • 必需的属性已存在 (jbake-type, jbake-status, project-thumbnail)

  • 引用的图像存在于`assets/img/portfolio/`

  • JBake 构建成功,无错误

  • 项目出现在作品集页面上

  • 单个项目页面显示正常

UC2 : 删除投资组合中的一项

标称通量

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ]

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "系统
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "系统
文件" as fs
participant "JBake
引擎" as jbake
participant "网站\n静态" as site
database "缓存
JBake" as cache

dev -> fs : Supprimer portfolio/projet-ancien.adoc
activate fs
fs --> dev : Fichier supprimé
deactivate fs

dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-*
activate fs
fs --> dev : Images supprimées
deactivate fs

dev -> cache : Nettoyer cache JBake
activate cache
cache --> dev : Cache vidé
deactivate cache

dev -> jbake : Rebuild complet (jbake -b)
activate jbake
jbake -> jbake : Scanner content/portfolio/
jbake -> jbake : Projet absent → non généré
jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé)
jbake -> site : Déployer nouveau build
deactivate jbake

dev -> site : Vérifier
activate site
site --> dev : Projet absent de la liste
deactivate site
@enduml

替代策略:归档

而不是永久删除,可以创建一个文件夹`content/portfolio/archive/`:

  • 移动文件而不是删除它

  • 可以轻松恢复

  • 保持 Git 历史更清晰

资源清理

  • 检查孤立的图像在`assets/img/portfolio/`

  • 删除未被其他项目引用的图片

  • 清理 JBake 缓存以避免幽灵引用

UC3 : 设置为未发布(草稿)

�额定通量

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ]

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "文件
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "文件
AsciiDoc" as file
participant "JBake
引擎" as jbake
participant "静态网站" as site

dev -> file : Ouvrir portfolio/projet.adoc
activate file

dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft

file --> dev : Sauvegardé
deactivate file

dev -> jbake : Rebuild (jbake -b)
activate jbake
jbake -> file : Parser le fichier
jbake -> jbake : Détecter status=draft
jbake -> jbake : Exclure de published_projects
jbake -> jbake : Ne pas créer page publique
note right
  Le projet existe toujours
  mais n'est pas publié
end note
jbake -> site : Générer site (sans ce projet)
deactivate jbake

dev -> site : Vérifier portfolio
activate site
site --> dev : Projet absent de la liste publique
deactivate site
@enduml

可能的状态

Diagram

典型用例

  • 项目正在起草中 : 创建草稿,准备好后发布

  • 临时保密项目:切换到草稿,等待客户确认

  • 重大更新:切换到草稿,编辑,重新发布

  • A/B testing : 在草稿中复制,测试,发布最佳版本

模板化架构

可重用模板的策略

Diagram

数据提取模式

JBake 会自动将 AsciiDoc 属性转换为在 Thymeleaf 中可访问的属性:

Diagram

命名约定

  • 项目属性 : 前缀`project-*` (ex: project-client, project-tech-stack)

  • 文件 : kebab-case (例如:`ecommerce-platform.adoc`)

  • 图片 : 前缀 项目名称 (例如:`ecommerce-platform-thumb.jpg`)

  • 模板 : 功能名称 (例如:project-card.html, tech-badge.html)

发布工作流

开发流水线

Diagram

环境

环境 用法 已接受状态

本地

开发和预览

草稿,已发布

布置

�预生产验证

仅发布

生产

公开网站

仅发布

可扩展性

添加新属性

为丰富数据模型,只需添加带前缀的新属性`project-*`:

  • `project-awards`奖项与表彰

  • `project-testimonial`客户引用

  • project-team-size: 团队规模

  • project-budget-range�预算范围

这些属性会在模板中自动可用,无需修改JBake引擎。

高级分类

Diagram

最佳实践

文件组织

  • 一个文件 = 一个项目 : 避免混合多个项目

  • 专用文件夹中的图像assets/img/portfolio/nom-projet/

  • 一致的命名 : 便于查找和维护

  • Versioning Git : 完全追踪修改

内容管理

  • 默认草稿状态 : 仅在准备好时发布

  • 发布前评审 : 质量和保密性验证

  • 完整元数据:填写所有相关字段

  • 丰富的叙事内容 : 不要仅限于元数据

性能

  • 优化图片 : 提交前压缩

  • 如需分页 : 如果项目数量超过20

  • Lazy loading : 图库图片按需加载

  • 浏览器缓存:适用于资源的适当标头

结论

此架构允许:

  • 使用简便 : 添加一个项目 = 创建一个文本文件

  • 灵活性 : 可通过新属性扩展

  • 可维护性 : 分离 内容/表现

  • 可追溯性 : 完整的 Git 版本控制

  • 自动化 : 可实现持续构建和部署

选择 AsciiDoc 能够与网站其余部分保持一致,同时提供专业投资组合所需的丰富元数据。

相关文章