Akka中reference.conf与application.conf的区别、用法及配置项问询

Hey there! As someone who's spent a lot of time building Akka applications, I totally get how these two config files can feel confusing when you're just starting out. Let's break this down clearly so you know exactly what each file does, how they work together, and what to put in each one.

At a high level, think of these files as a "defaults vs customizations" pair:

• reference.conf: This is the default configuration provided by Akka (and any other libraries you use that rely on Typesafe Config). It ships right with the Akka jars and defines all the out-of-the-box settings for things like actor dispatchers, logging, cluster behavior, and more.
• application.conf: This is your application's custom configuration file. It's where you'll override Akka's default settings to match your app's needs, and add any application-specific config that Akka doesn't care about (like database URLs or API keys).

Akka uses the Typesafe Config library under the hood, which follows a clear priority order when loading configs:

1. First, it loads all reference.conf files from every dependency in your project (Akka itself, Akka HTTP, any custom Akka libraries you're using, etc.) and merges them into a single set of default settings.
2. Then it loads your application.conf, and any settings you define here will override the matching settings from the merged reference.conf.
3. If there's a setting in application.conf that doesn't exist in reference.conf, it just adds it to the config tree for your app to use.

Pro tip: You can print config values in your code to verify which settings are active (e.g., system.settings.config.getString("akka.loglevel")).

reference.conf (For Library/Framework Authors Only) #

If you're just building an Akka application (not a reusable library), you'll never need to create or modify a reference.conf—this is strictly for the folks who build Akka itself or other Akka-based libraries. For them:

• Put default, generic settings that users might want to override later. These should be sensible defaults that work for most use cases.
• Example from Akka's own reference.conf:

akka {
  actor {
    default-dispatcher {
      fork-join-executor {
        parallelism-min = 8
        parallelism-factor = 3.0
        parallelism-max = 64
      }
    }
    loglevel = "INFO"
  }
}

• Rule of thumb: Don't put environment-specific or app-specific settings here—keep it universal.

application.conf (For Application Developers) #

This is your playground. Here's what belongs here:

• Overrides for Akka defaults: If you need to tweak Akka's behavior (like reducing the default dispatcher's thread count for a small app, or enabling debug logging), put those changes here.
• Application-specific config: Any settings your app needs that aren't part of Akka's core—database connection details, API timeouts, feature flags, etc.
• Environment-specific settings: You can split these into separate files (e.g., application-dev.conf, application-prod.conf) and include them in your main application.conf like this:

  include "application-dev"
  
  # Common settings that apply to all environments
  akka {
    actor {
      loglevel = "DEBUG"
    }
  }
  

Example of a typical application.conf:

# Override Akka's default dispatcher to fit our small app
akka {
  actor {
    default-dispatcher {
      fork-join-executor {
        parallelism-min = 4
        parallelism-factor = 2.0
      }
    }
    loglevel = "DEBUG"
  }
}

# Our app's custom settings
my-retail-app {
  database {
    url = "jdbc:postgresql://localhost:5432/retail_db"
    username = "dev_user"
    password = "dev_pass"
  }
  inventory {
    restock-threshold = 10
    api-timeout = 3s
  }
}

• Never modify reference.conf: Don't edit the one that comes with Akka—always use application.conf to override settings. Modifying the original file will cause headaches when you update Akka versions.
• Keep it lean: Only override the settings you need to change. Don't copy the entire reference.conf into your application.conf—that's a maintenance nightmare.
• Split environment configs: Keeping dev, test, and prod settings separate makes it easier to switch between environments without editing the main file.
• Validate your config: Add checks in your app to ensure critical settings are present, or use Akka's built-in config validation tools to catch typos early.

内容的提问来源于stack exchange，提问作者pik4