Apache Causeway App demopjpa 镜像文档

1. 镜像概述和主要用途

本镜像是基于 Apache Causeway 框架构建的演示应用（demopjpa），集成了 Java Persistence API（JPA）用于数据持久化。Apache Causeway 是一款专注于领域驱动设计（DDD）的低代码开发框架，支持通过领域模型自动生成 UI、API 和业务逻辑。本镜像的核心用途是：

• 展示 Apache Causeway 框架的核心功能（如领域模型驱动开发、零代码 CRUD 操作）；
• 演示 JPA 与 Apache Causeway 的集成实践（包括实体管理、事务控制、数据持久化）；
• 提供可直接运行的示例环境，供开发者快速了解框架使用方法。

2. 核心功能和特性

2.1 核心功能

• 领域模型驱动开发：基于 JPA 实体定义领域模型，自动生成业务逻辑基础；
• 零代码 CRUD 操作：通过框架约定自动支持实体的创建、查询、更新、删除；
• JPA 数据持久化：集成 JPA 规范，支持与关系型数据库（如 H2、MySQL）交互；
• 事务管理：内置事务支持，确保数据操作的原子性和一致性；
• Web UI 自动生成：通过 Apache Causeway Wicket UI 模块提供可视化操作界面；
• REST API 暴露：可选集成 RESTful API，支持通过 HTTP 接口访问业务功能。

2.2 主要特性

• 约定优于配置：减少手动配置，通过领域模型注解（如 @Entity、@Property）自动生成功能；
• 数据验证：支持 JPA 标准验证注解（如 @NotNull、@Size）及自定义业务规则校验；
• 扩展性：支持自定义业务逻辑扩展（如领域服务、事件监听）；
• 轻量级部署：基于 Java 运行时，镜像体积精简，适合快速启动；
• 默认 H2 数据库：内置 H2 内存/文件数据库，开箱即用（支持切换至外部数据库）。

3. 使用场景和适用范围

3.1 典型使用场景

• 框架学*与评估**：供开发者快速体验 Apache Causeway 的核心能力及 JPA 集成方式；
• 技术演示：向团队或客户展示低代码 DDD 开发流程及效果；
• 原型验证：基于镜像快速搭建业务原型，验证领域模型设计合理性。

3.2 适用范围

• 环境限制：仅用于开发、测试或演示环境，不建议直接用于生产环境；
• 用户群体：Java 开发者、架构师、DDD 实践者（需具备 JPA 基础）；
• 数据库支持：默认支持 H2（内置），可通过配置扩展至 MySQL、PostgreSQL 等关系型数据库。

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker 引擎（推荐 20.10+ 版本）；
• 网络环境可访问 Docker 镜像仓库（或手动加载本地镜像）。

4.2 获取镜像

假设镜像托管于 Docker Hub，通过以下命令拉取（如无公开仓库，需替换为实际镜像源）：

bash
docker pull apache/causeway-demopjpa:latest

4.3 快速启动（docker run）

通过 docker run 直接启动容器，默认使用内置 H2 内存数据库（数据仅临时存储，容器重启后丢失）：

bash
docker run -d \
  --name causeway-demopjpa \
  -p 8080:8080 \  # 映射容器 8080 端口到主机
  -e LOG_LEVEL=INFO \  # 日志级别（默认 INFO）
  apache/causeway-demopjpa:latest

参数说明：

• -p 8080:8080：Web UI 和 API 端口映射（默认端口 8080）；
• --name：指定容器名称，便于管理；
• -e LOG_LEVEL：调整日志级别（可选值：DEBUG、INFO、WARN、ERROR）。

4.4 持久化配置（数据卷挂载）

如需持久化 H2 数据库数据（避免容器重启后数据丢失），通过数据卷挂载 H2 数据文件目录：

bash
docker run -d \
  --name causeway-demopjpa \
  -p 8080:8080 \
  -v causeway-data:/app/data \  # 挂载数据卷至容器内 H2 数据目录
  -e DB_URL=jdbc:h2:file:/app/data/demopjpa;DB_CLOSE_ON_EXIT=FALSE \  # H2 文件数据库路径
  -e DB_USER=sa \  # 数据库用户名（默认 sa）
  -e DB_PASSWORD=demopass \  # 数据库密码（默认空，建议设置）
  apache/causeway-demopjpa:latest

数据卷说明：

• causeway-data 为 Docker 命名卷，数据持久化至主机 /var/lib/docker/volumes/causeway-data/_data。

4.5 Docker Compose 部署

通过 docker-compose.yml 配置多服务环境（如集成外部 MySQL 数据库），示例如下：

yaml
version: '3.8'

services:
  # 应用服务
  causeway-app:
    image: apache/causeway-demopjpa:latest
    ports:
      - "8080:8080"
    environment:
      - DB_TYPE=mysql  # 指定数据库类型（默认 h2）
      - DB_URL=jdbc:mysql://mysql:3306/demopjpa?useSSL=false  # MySQL 连接 URL
      - DB_USER=root
      - DB_PASSWORD=rootpass
      - LOG_LEVEL=DEBUG
    depends_on:
      - mysql  # 依赖 MySQL 服务
    restart: unless-stopped

  # MySQL 数据库服务（外部数据库示例）
  mysql:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=demopjpa  # 自动创建数据库
    volumes:
      - mysql-data:/var/lib/mysql  # MySQL 数据持久化
    restart: unless-stopped

volumes:
  mysql-data:  # MySQL 数据卷

启动命令：

bash
docker-compose up -d  # 后台启动服务

4.6 配置参数说明

4.6.1 环境变量

4.6.2 数据卷挂载

5. 访问应用

容器启动后，可通过以下方式访问服务：

5.1 Web UI

• 地址：http://<主机IP>:8080
• 默认登录凭证：admin/pass（管理员账户，用于演示环境）
• 功能：通过可视化界面操作领域实体（如创建、查询、删除数据）。

5.2 REST API（可选）

若启用 REST 模块，API 基础路径为 http://<主机IP>:8080/restful/objects，支持通过 HTTP 方法（GET/POST/PUT/DELETE）操作实体。示例：

bash
# 查询所有实体
curl -u admin:pass http://localhost:8080/restful/objects/demopjpa.Customer

6. 注意事项

• 生产环境禁用：本镜像为演示用途，未经过安全加固和性能优化，禁止直接用于生产环境；
• 数据备份：若使用文件数据库（如 H2 文件模式），需定期备份挂载的数据卷；
• 密码修改：演示环境默认凭证（admin/pass）需在实际测试时修改，避免未授权访问；
• 版本兼容性：镜像版本需与 Apache Causeway 框架版本匹配（如 latest 对应最新稳定版）。