はじめに (対象読者・この記事でわかること)

この記事は、Java でのアプリケーション開発を始めたばかりの方や、設定ファイルを外部化したいと考えている中級者の開発者を対象にしています。
プロパティファイルを「なんとなく使っている」けど「文字化けする」「値を読み込めない」「本番環境で差し替えたい」といった悩みを解決します。
この記事を読むことで、プロパティファイルの作成から読み書き、運用時の文字化け対策、セキュアな暗号化まで、実務で使える一連の手法を習得できます。
サンプルコードは Java 17 以降の記法で動作確認済みです。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - Java の基本的な文法（クラス・メソッドの記述） - Maven または Gradle によるビルドの基礎 - 文字コード（UTF-8 / ISO-8859-1）の違いをある程度意識した経験

プロパティファイルとは何か、なぜ必要なのか

プロパティファイル（拡張子 .properties）は、Java が標準でサポートする設定ファイルフォーマットです。
データベース接続情報、外部 API の URL、機能フラグなど、アプリケーションの振る舞いをコードから切り離して管理できるため、本番・検証・開発環境ごとに値を差し替えるだけでデプロイが完結します。
XML や YAML と比べて記述が軽量であり、Spring Boot をはじめとする主要フレームワークでもデファクトスタンダードとして採用されているため、覚えて損はありません。
ただし、デフォルトエンコーディングが ISO-8859-1 であるため、日本語をそのまま記述すると文字化けするという落とし穴もあります。次章以降で、それを回避する実践的なテクニックをお伝えします。

実践：プロパティファイルの作成から暗号化まで

ここでは、①プロパティファイルを作成し、②Java コードから読み込み、③文字化けを防ぎ、④パスワード等の機密情報を暗号化するまでの一連の手順を解説します。
すべてのコードは GitHub のサンプルリポジトリに置いていますので、手元にコピーして動かしながら読み進めてください。

ステップ1：プロパティファイルを作成する

src/main/resources に application.properties を新規作成します。
ISO-8859-1 以外の文字（日本語や絵文字）を含める場合は、Unicode エスケープ（\u30C6\u30B9\u30C8 形式）するか、後述の「UTF-8 対応」手順を先に実施してください。

Properties

# データベース接続情報
db.host=localhost
db.port=5432
db.name=sample_db

# 機能フラグ
feature.newUI=true

# 日本語メッセージ（Unicode エスケープ）
msg.greeting=\u3053\u3093\u306B\u3061\u306F\u3001{0}\u3055\u3093

ビルドツールが Maven の場合、pom.xml に以下を追加してリソース扱いにします（Gradle なら processResources タスクがデフォルトでリソースをコピーしてくれます）。

Xml

<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering> <!-- 変数置き換えを有効にする場合 -->
    </resource>
  </resources>
</build>

ステップ2：Java コードから読み込む

java.util.Properties クラスを使う最も簡単な方法を示します。
ファイル名を変数化しておくと、単体テスト時に別のプロパティを読みやすくなります。

Java

public class ConfigLoader {
    private static final Properties PROPS = new Properties();

    static {
        try (InputStream is = ConfigLoader.class
                .getClassLoader()
                .getResourceAsStream("application.properties")) {
            if (is == null) throw new IllegalStateException("ファイル不在");
            PROPS.load(is);
        } catch (IOException e) {
            throw new ExceptionInInitializerError(e);
        }
    }

    public static String get(String key) {
        return PROPS.getProperty(key);
    }

    public static boolean getBoolean(String key) {
        return Boolean.parseBoolean(PROPS.getProperty(key, "false"));
    }
}

Spring Boot を使っている場合は、@ConfigurationProperties を活用すると、クラスに自動バインドできて便利です。

Java

@Component
@ConfigurationProperties(prefix = "db")
@Data
public class DatabaseProps {
    private String host;
    private int port;
    private String name;
}

ステップ3：文字化けを防ぐ（UTF-8 対応）

デフォルトの Properties#load(InputStream) は ISO-8859-1 として読み込むため、日本語をそのまま書くと文字化けします。
Java 9 以降では load(Reader) が追加されたため、InputStreamReader で UTF-8 を明示すれば解決します。

Java

try (Reader reader = new InputStreamReader(
        is, StandardCharsets.UTF_8)) {
    PROPS.load(reader);
}

もし Java 8 以下を使わざるを得ない場合は、プロパティファイル側を \uXXXX 形式に変換するプラグイン（native2ascii-maven-plugin 等）をビルドフェーズに組み込む方法が確実です。

ステップ4：機密値を暗号化して扱う

本番環境のパスワードや API トークンをプレーンテキストで記載するのはリスクが高いため、Jasypt（Java Simplified Encryption）を使って暗号化します。
Spring Boot と組み合わせると、自動的に復号してくれるので便利です。

  1. 依存関係を追加（Maven 例）
Xml

<dependency>
  <groupId>com.github.ulisesbocchio</groupId>
  <artifactId>jasypt-spring-boot-starter</artifactId>
  <version>3.0.5</version>
</dependency>
  1. 暗号化された値を生成
Bash

java -cp jasypt-1.9.3.jar \
  org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
  algorithm=PBEWITHHMACSHA512ANDAES_256 \
  password=masterKey \
  input=MySecretPassword

出力例：ENC(9rG7zX3...)
この文字列をプロパティに記載します。

  1. プロパティファイルに記載
Properties

db.password=ENC(9rG7zX3...)
  1. ランタイムにマスターキーを環境変数から読み込む
Yaml

# application.yml（Spring Boot）
jasypt:
  encryptor:
    password: ${JASYPT_ENCRYPTOR_PASSWORD}

これで、Git には暗号化済みの値をプッシュしておき、本番マシンだけに環境変数 JASYPT_ENCRYPTOR_PASSWORD を設定すれば、セキュアに運用できます。

ハマりがちなポイントと解決策

現象 原因 解決策
日本語が文字化け Properties#load(InputStream) を使っている load(Reader) に UTF-8 リーダーを渡す
Spring Boot で値がバインドされない getter/setter がない、または prefix ミス Lombok @Data 等で getter/setter を生成し、@ConfigurationProperties(prefix="...") を正確に記載
Jasypt で起動時に DecryptionException マスターキーが環境変数に存在しない CI/CD パイプラインで本番キーを注入するか、Kubernetes の Secret としてマウントする
プロパティファイルが読めない（null になる） クラスパスにファイルが存在しない mvn clean package して target/classes にファイルがコピーされるか確認する

まとめ

本記事では、Java プロパティファイルの作成、読み書き、文字化け対策、そして機密情報の暗号化まで、実務で使える一連の手法を紹介しました。

  • プロパティファイルはシンプルなフォーマットながら、エンコーディングや運用面で落とし穴がある
  • Java 9 以降なら UTF-8 リーダーを使うだけで文字化けを回避できる
  • Spring Boot + Jasypt を組み合わせることで、セキュアかつ簡単に機密値を管理できる

プロパティファイルを正しく扱うだけで、デプロイの手間が減り、セキュリティリスクも低減します。
次回は、Spring Cloud Config を使ってプロパティを集中管理する方法や、Kubernetes ConfigMap/Secret との連携テクニックを紹介する予定です。

参考資料