Java数据库应用原型

这是一个Java 数据库应用原型，使用 Spring Boot 和容器进行测试、Keycloak 提供安全、PostgreSQL 提供数据持久化的，带有 REST 和安全功能。

在工作中开发时，我多次需要一个简单应用的模板，以便基于此模板开始为手头的项目添加特定代码。
在本文中，我将创建一个简单的 Java 应用程序，它连接到数据库，暴露一些 REST 端点，并使用基于角色的访问来保护这些端点。
目的是拥有一个最小化且功能齐全的应用程序，然后可以针对特定任务进行定制。
对于数据库，我们将使用 PostgreSQL；对于安全，我们将使用 Keycloak，两者都通过容器部署。在开发过程中，我使用 podman 来测试容器是否正确创建（作为 docker 的替代品——它们在大多数情况下可以互换）作为一次学习体验。
应用程序本身是使用 Spring Boot 框架开发的，并使用 Flyway 进行数据库版本管理。
所有这些技术都是 Java EE 领域业界标准，在项目中被使用的可能性很高。

我们构建原型的核心需求是一个图书馆应用程序，它暴露 REST 端点，允许创建作者、书籍以及它们之间的关系。这将使我们能够实现一个多对多关系，然后可以将其扩展用于任何可以想象的目的。
完整可用的应用程序可以在 https://github.com/ghalldev/db_proto 找到。
本文中的代码片段取自该代码库。

在创建容器之前，请确保使用您偏好的值定义以下环境变量（教程中故意省略了它们，以避免传播多个用户使用的默认值）：

DOCKER_POSTGRES_PASSWORD
DOCKER_KEYCLOAK_ADMIN_PASSWORD
DOCKER_GH_USER1_PASSWORD

配置 PostgreSQL：

docker container create --name gh_postgres --env POSTGRES_PASSWORD=$DOCKER_POSTGRES_PASSWORD --env POSTGRES_USER=gh_pguser --env POSTGRES_INITDB_ARGS=--auth=scram-sha-256 --publish 5432:5432 postgres:17.5-alpine3.22
docker container start gh_postgres

配置 Keycloak:
首先是容器的创建并启动：

docker container create --name gh_keycloak --env DOCKER_GH_USER1_PASSWORD=$DOCKER_GH_USER1_PASSWORD --env KC_BOOTSTRAP_ADMIN_USERNAME=gh_admin --env KC_BOOTSTRAP_ADMIN_PASSWORD=$DOCKER_KEYCLOAK_ADMIN_PASSWORD --publish 8080:8080 --publish 8443:8443 --publish 9000:9000 keycloak/keycloak:26.3 start-dev
docker container start gh_keycloak

在容器启动并运行后，我们可以继续创建领域、用户和角色（这些命令必须在正在运行的容器内部执行）：

cd $HOME/bin
./kcadm.sh config credentials --server http://localhost:8080 --realm master --user gh_admin --password $KC_BOOTSTRAP_ADMIN_PASSWORD
./kcadm.sh create realms -s realm=gh_realm -s enabled=true
./kcadm.sh create users -s username=gh_user1 -s email="gh_user1@email.com" -s firstName="gh_user1firstName" -s lastName="gh_user1lastName" -s emailVerified=true -s enabled=true -r gh_realm
./kcadm.sh set-password -r gh_realm --username gh_user1 --new-password $DOCKER_GH_USER1_PASSWORD
./kcadm.sh create roles -r gh_realm -s name=viewer -s 'description=Realm role to be used for read-only features'
./kcadm.sh add-roles --uusername gh_user1 --rolename viewer -r gh_realm
./kcadm.sh create roles -r gh_realm -s name=creator -s 'description=Realm role to be used for create/update features'
./kcadm.sh add-roles --uusername gh_user1 --rolename creator -r gh_realm
ID_ACCOUNT_CONSOLE=$(./kcadm.sh get clients -r gh_realm --fields id,clientId | grep -B 1 '"clientId" : "account-console"' | grep -oP '[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}')
./kcadm.sh update clients/$ID_ACCOUNT_CONSOLE -r gh_realm -s 'fullScopeAllowed=true' -s 'directAccessGrantsEnabled=true'

用户 gh_user1 在领域 gh_realm 中被创建，并拥有 viewer 和 creator 角色。

您可能已经注意到，我们没有创建新的客户端，而是使用了 Keycloak 自带的一个默认客户端：account-console。这是为了方便起见，在实际场景中，您会创建一个特定的客户端，然后将其更新为具有 fullScopeAllowed（这会导致领域角色被添加到令牌中——默认情况下不添加）和 directAccessGrantsEnabled（允许通过 Keycloak 的 openid-connect/token 端点生成令牌，在我们的例子中使用 curl）。

创建的角色随后可以在 Java 应用程序内部使用，以根据我们约定的契约来限制对某些功能的访问——viewer 只能访问只读操作，而 creator 可以执行创建、更新和删除操作。当然，同样地，可以根据任何原因创建各种角色，只要约定的契约被明确定义并被所有人理解。
角色还可以进一步添加到组中，但本教程不包含这部分内容。

但是，在实际使用这些角色之前，我们必须告诉 Java 应用程序如何提取角色——这是必须的，因为 Keycloak 将角色添加到 JWT 的方式是其特有的，所以我们必须编写一段自定义代码，将其转换为 Spring Security 可以使用的东西：

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {// 遵循与 org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter 相同的模式Converter<Jwt, Collection<GrantedAuthority>> keycloakRolesConverter = new Converter<>() {private static final String DEFAULT_AUTHORITY_PREFIX = "ROLE_";//https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java#L901private static final String KEYCLOAK_REALM_ACCESS_CLAIM_NAME = "realm_access";private static final String KEYCLOAK_REALM_ACCESS_ROLES = "roles";@Overridepublic Collection<GrantedAuthority> convert(Jwt source) {Collection<GrantedAuthority> grantedAuthorities = new ArrayList<>();Map<String, List<String>> realmAccess = source.getClaim(KEYCLOAK_REALM_ACCESS_CLAIM_NAME);if (realmAccess == null) {logger.warn("No " + KEYCLOAK_REALM_ACCESS_CLAIM_NAME + " present in the JWT");return grantedAuthorities;}List<String> roles = realmAccess.get(KEYCLOAK_REALM_ACCESS_ROLES);if (roles == null) {logger.warn("No " + KEYCLOAK_REALM_ACCESS_ROLES + " present in the JWT");return grantedAuthorities;}roles.forEach(role -> grantedAuthorities.add(new SimpleGrantedAuthority(DEFAULT_AUTHORITY_PREFIX + role)));return grantedAuthorities;}};JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(keycloakRolesConverter);return jwtAuthenticationConverter;
}

在 AppConfiguration 类中还完成了其他重要配置，例如启用方法安全性和禁用 CSRF。

现在我们可以在 REST 控制器中使用 @org.springframework.security.access.prepost.PreAuthorize 注解来限制访问：

@PostMapping("/author")
@PreAuthorize("hasRole('creator')")
public void addAuthor(@RequestParam String name, @RequestParam String address) {authorService.add(new AuthorDto(name, address));
}@GetMapping("/author")
@PreAuthorize("hasRole('viewer')")
public String getAuthors() {return authorService.allInfo();
}

通过这种方式，只有成功通过身份验证且拥有 hasRole 中列出的角色的用户才能调用端点，否则他们将收到 HTTP 403 Forbidden 错误。

在容器启动并配置完成后，Java 应用程序可以启动了，但在启动之前需要添加数据库密码——这可以通过环境变量完成（下面是一个 Linux shell 示例）：

export SPRING_DATASOURCE_PASSWORD=$DOCKER_POSTGRES_PASSWORD

现在，如果一切正常启动并运行，我们可以使用 curl 来测试我们的应用程序（以下所有命令均为 Linux shell 命令）。

使用之前创建的用户 gh_user1 登录并提取身份验证令牌：

KEYCLOAK_ACCESS_TOKEN=$(curl -d 'client_id=account-console' -d 'username=gh_user1' -d "password=$DOCKER_GH_USER1_PASSWORD" -d 'grant_type=password' 'http://localhost:8080/realms/gh_realm/protocol/openid-connect/token' | grep -oP '"access_token":"\K[^"]*')

创建一个新作者（这将测试 creator 角色是否有效）：

curl -X POST --data-raw 'name="GH_name1"&address="GH_address1"' -H "Authorization: Bearer $KEYCLOAK_ACCESS_TOKEN" 'localhost:8090/library/author'

检索库中的所有作者（这将测试 viewer 角色是否有效）：

curl -X GET -H "Authorization: Bearer $KEYCLOAK_ACCESS_TOKEN" 'localhost:8090/library/author'

至此，您应该拥有了创建自己的 Java 应用程序所需的一切，可以根据需要对其进行扩展和配置。

---

【注】本文译自：Java Spring Boot Template With PostgreSQL, Keycloak Securit