Apache Causeway App Simpleapp 镜像文档

1. 镜像概述和主要用途

1.1 概述

Apache Causeway App Simpleapp（以下简称 Simpleapp）是基于 Apache Causeway 框架构建的官方示例应用镜像。Apache Causeway 是一个开源领域驱动设计（DDD）应用开发框架，支持快速构建业务应用，自动生成 UI 界面、REST API 及数据持久层逻辑。Simpleapp 作为框架的官方示例，集成了 Apache Causeway 的核心功能，旨在为开发者提供开箱即用的演示环境和基础开发模板。

1.2 主要用途

• 框架学***：帮助开发者快速熟悉 Apache Causeway 的核心概念（如领域对象、视图模型、安全授权等）及使用方式。
• 原型开发：作为业务应用原型的基础模板，支持快速验证业务逻辑和交互流程。
• 功能演示：展示 Apache Causeway 自动生成 UI、REST API、事务管理等核心能力。

2. 核心功能和特性

2.1 核心功能

• 领域驱动设计（DDD）支持：原生支持实体（Entity）、值对象（Value Object）、领域服务（Domain Service）等 DDD 核心组件。
• 自动生成 UI：基于领域模型自动生成响应式 Web 界面，支持 CRUD 操作、数据验证及权限控制。
• 自动生成 REST API：无需手动编写接口，框架根据领域模型自动生成符合 REST 规范的 API，支持 JSON 数据交互。
• 安全控制：集成基于角色的访问控制（RBAC），支持用户认证、权限粒度控制（如对象级、操作级权限）。
• 事务管理：内置事务支持，确保业务操作的原子性和一致性。

2.2 特性

• 轻量化部署：基于 Java 运行时，支持通过 Docker 快速启动，无需复杂环境配置。
• 内置演示数据：包含预设领域模型（如产品、订单、客户等）及测试数据，开箱即可运行。
• 多数据库支持：默认集成 H2 内存数据库（适合快速启动），可通过配置切换至 MySQL、PostgreSQL 等生产级数据库。
• 可扩展性：支持通过挂载外部配置文件或自定义 JAR 包扩展功能（如添加自定义领域模型、业务规则）。

3. 使用场景和适用范围

3.1 适用场景

• 开发者学***：新手通过运行 Simpleapp 了解 Apache Causeway 的核心功能及开发流程。
• 业务原型验证：产品经理或开发团队基于示例模型快速修改，验证业务流程可行性。
• 基础项目模板：开发者可基于 Simpleapp 镜像扩展，构建符合实际业务需求的应用（需替换示例领域模型）。

3.2 适用范围

• 环境限制：主要用于开发/测试环境，生产环境需进一步定制（如替换默认数据库、增强安全配置、优化性能）。
• 用户群体：面向 Apache Causeway 框架的学***者、业务应用开发者及需要快速交付原型的团队。

4. 使用方法和配置说明

4.1 环境要求

• Docker 19.03+ 或 Docker Desktop 安装完成。
• 网络环境：需允许容器访问外部网络（用于拉取镜像，可选）。
• 资源要求：建议至少 2GB 内存（运行时包含 Java 进程及内置数据库）。

4.2 镜像获取

从 Docker Hub 拉取官方镜像（若未发布，可通过源码构建，此处假设镜像名称为 apache/causeway-simpleapp）：

docker pull apache/causeway-simpleapp:latest

4.3 快速启动（默认配置）

使用默认配置启动容器（内置 H2 内存数据库，数据仅保存在容器运行期间，重启后丢失）：

docker run -d -p 8080:8080 --name causeway-simpleapp apache/causeway-simpleapp:latest

• 访问 UI：浏览器打开 http://localhost:8080，默认用户名/密码：sven/pass。
• 访问 REST API：通过 http://localhost:8080/restful/objects 查看 API 根目录（支持 Swagger 文档，访问 http://localhost:8080/swagger-ui.html）。

4.4 持久化数据配置

如需保留数据（如测试过程中避免数据丢失），可挂载外部目录存储 H2 数据库文件：

docker run -d \
  -p 8080:8080 \
  -v /本地目录/persistence:/app/persistence \  # 挂载外部目录存储数据库文件
  -e CAUSEWAY_DB_TYPE=H2 \
  -e CAUSEWAY_DB_URL=jdbc:h2:/app/persistence/simpleapp;AUTO_SERVER=TRUE \
  --name causeway-simpleapp apache/causeway-simpleapp:latest

4.5 对接外部数据库（如 MySQL）

若需使用 MySQL 作为持久化存储，配置环境变量如下：

docker run -d \
  -p 8080:8080 \
  -e CAUSEWAY_DB_TYPE=MYSQL \
  -e CAUSEWAY_DB_URL=jdbc:mysql://mysql-host:3306/simpleapp?useSSL=false \
  -e CAUSEWAY_DB_USER=root \
  -e CAUSEWAY_DB_PASSWORD=mysql-password \
  --name causeway-simpleapp apache/causeway-simpleapp:latest

注：需提前创建 MySQL 数据库 simpleapp，并确保容器可访问 MySQL 服务（如通过 --link 或 Docker 网络连接）。

4.6 Docker Compose 配置示例

通过 docker-compose.yml 集成 Simpleapp 与 MySQL（一键启动应用及依赖服务）：

version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: mysql-password
      MYSQL_DATABASE: simpleapp
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-pmysql-password"]
      interval: 10s
      timeout: 5s
      retries: 5

  causeway-simpleapp:
    image: apache/causeway-simpleapp:latest
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      CAUSEWAY_DB_TYPE: MYSQL
      CAUSEWAY_DB_URL: jdbc:mysql://mysql:3306/simpleapp?useSSL=false
      CAUSEWAY_DB_USER: root
      CAUSEWAY_DB_PASSWORD: mysql-password
      CAUSEWAY_LOG_LEVEL: INFO
    restart: unless-stopped

volumes:
  mysql-data:

启动命令：

docker-compose up -d

5. 配置参数说明

5.1 核心环境变量

5.2 扩展配置

如需自定义领域模型或业务规则，可通过挂载外部 JAR 包（如自定义模块）至容器的 /app/extensions 目录：

docker run -d \
  -p 8080:8080 \
  -v /本地扩展目录:/app/extensions \  # 挂载包含自定义 JAR 的目录
  --name causeway-simpleapp apache/causeway-simpleapp:latest

6. 访问与验证

6.1 UI 界面访问

• 地址：http://<容器IP或主机IP>:8080
• 默认登录用户：sven，密码：pass
• 功能验证：通过左侧菜单访问“产品”“订单”模块，尝试创建/编辑数据，验证 UI 交互及数据持久化。

6.2 REST API 验证

• API 根地址：http://<容器IP或主机IP>:8080/restful/objects
• 示例接口（获取产品列表）：

  curl -u sven:pass http://localhost:8080/restful/objects/product
  

• Swagger 文档：访问 http://localhost:8080/swagger-ui.html 查看 API 详情及测试界面。

7. 注意事项

• 生产环境适配：Simpleapp 为示例应用，生产环境需替换默认数据库（如使用 MySQL/PostgreSQL）、增强安全配置（如修改默认密码、启用 HTTPS）及优化性能（如调整 JVM 参数）。
• 数据持久化：使用 H2 内存数据库时，容器重启后数据丢失，需通过挂载目录或切换至外部数据库实现持久化。
• 版本兼容性：镜像版本需与 Apache Causeway 框架版本匹配，建议使用 latest 标签获取最新稳定版。