# YAI Nexus Configuration
🚀 **高质量的 Python 配置管理库** - 基于 Provider 模式，支持多种配置源
## 🎬 快速上手 (Hello, World!)
这是体验 `yai-nexus-configuration` 核心功能的最快方式。我们将通过一个完整的、可运行的示例，展示“**定义 -> 创建 -> 注册 -> 获取**”的黄金路径。
### 1. 项目结构
首先，请像这样组织您的项目文件：
```
your-project/
├── configs/
│ └── DEFAULT_GROUP/
│ └── app_config.json
└── main.py
```
### 2. 创建配置文件
在 `configs/DEFAULT_GROUP/` 目录下创建一个名为 `app_config.json` 的文件，内容如下：
```json
{
"database_url": "sqlite:///./test.db",
"retries": 5,
"api_key": "a-secret-key-from-environment"
}
```
> **提示**: 在未来的版本中，我们将支持 `${VAR}` 格式的环境变量自动替换，以增强安全性。
### 3. 编写 Python 代码 (`main.py`)
现在，创建 `main.py` 并复制以下代码。它包含了使用本库的所有核心步骤。
```python
from yai_nexus_configuration import NexusConfig, nexus_config, NexusConfigManager
# 步骤 1: 定义一个与 JSON 结构匹配的配置类
# @nexus_config 装饰器将类与配置文件关联起来
@nexus_config(data_id="app_config.json", group="DEFAULT_GROUP")
class AppConfig(NexusConfig):
database_url: str
retries: int = 3 # 您可以提供默认值
api_key: str
# 步骤 2: 使用工厂方法创建管理器
# `with` 语句能确保资源被正确管理和释放
with NexusConfigManager.with_file(base_path="configs") as manager:
# 步骤 3: 向管理器注册您的配置类
manager.register(AppConfig)
# 步骤 4: 从管理器中获取类型安全的配置实例
config = manager.get_config(AppConfig)
# 步骤 5: 像使用普通对象一样使用您的配置
print(f"数据库 URL: {config.database_url}")
print(f"重试次数: {config.retries}")
print(f"API 密钥: {config.api_key}")
# 运行此脚本，您将看到从文件中加载并经过验证的配置！
```
**效果**: 这个“黄金路径”示例清晰地展示了本库的核心设计思想，能帮助您快速上手，避免常见的使用陷阱。
---
## ✨ 主要特性
- 🎯 **简洁优雅的 API** - 采用工厂模式，一行代码创建管理器
- 🔒 **线程安全** - 所有操作都是线程安全的，适用于多线程环境
- 🔄 **自动配置更新** - 实时监听配置源变更，自动更新本地配置
- 🧩 **可扩展架构** - 基于 Provider 模式，轻松支持新的配置源
- ✅ **类型安全** - 完整的类型提示支持，基于 Pydantic 数据验证
- 📦 **零依赖冲突** - 精心设计的依赖管理，避免版本冲突
## 🏗️ 架构设计
YAI Nexus Configuration 采用了经过深度思考的 **方案 E（工厂模式）** 架构：
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ 用户代码 │────│ NexusConfigManager │────│ ConfigStore │
│ │ │ (工厂 + 管理) │ │ (线程安全存储) │
└─────────────────┘ └──────────┬───────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ AbstractProvider │
│ (抽象层) │
└─────────┬────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ NacosProvider│ │ 未来的Provider│
│ │ │ (Apollo等) │
└──────────────┘ └──────────────┘
```
### 核心优势
- **高内聚，低耦合**: Provider 抽象层完全隔离了配置源实现
- **面向接口编程**: 核心逻辑只依赖抽象接口，便于测试和扩展
- **工厂模式**: 提供简洁的创建接口，隐藏复杂的初始化逻辑
- **单一职责**: 每个组件都有明确的职责边界
## 🔧 支持的配置源
| 配置源 | 状态 | 工厂方法 | 说明 |
|--------|------|----------|------|
| **Nacos** | ✅ 已支持 | `NexusConfigManager.with_nacos()` | 阿里巴巴开源的配置中心 |
| **Apollo** | 🚧 规划中 | `NexusConfigManager.with_apollo()` | 携程开源的配置中心 |
| **Etcd** | 🚧 规划中 | `NexusConfigManager.with_etcd()` | 分布式键值存储 |
| **本地文件** | ✅ 已支持 | `NexusConfigManager.with_file()` | 本地 JSON/YAML/ENV 文件 |
## 📖 详细文档
### 文件配置使用
文件提供者可以根据文件扩展名（`.json` 或 `.yaml`）自动选择解析器。
**1. 定义多个配置类**
```python
from yai_nexus_configuration import NexusConfigManager, NexusConfig, nexus_config
# JSON 配置
@nexus_config(data_id="app.json", group="DEFAULT_GROUP")
class AppConfig(NexusConfig):
app_name: str
debug: bool
# YAML 配置 (需要安装 PyYAML)
@nexus_config(data_id="database.yaml", group="PROD")
class DbConfig(NexusConfig):
host: str
port: int
```
**2. 使用同一个管理器**
```python
# 只需要一个管理器实例
with NexusConfigManager.with_file(
base_path="configs", # 配置文件根目录
watch_interval=1.0, # 文件监听间隔（秒）
) as manager:
# 你的文件结构:
# configs/
# ├── DEFAULT_GROUP/
# │ └── app.json
# └── PROD/
# └── database.yaml
# 批量注册
manager.register(AppConfig, DbConfig)
# 获取配置
app_config = manager.get_config(AppConfig)
db_config = manager.get_config(DbConfig)
print(f"应用: {app_config.app_name}, 数据库主机: {db_config.host}")
```
### Nacos 配置使用
```python
# 创建管理器（建议从环境变量获取敏感信息）
manager = NexusConfigManager.with_nacos(
server_addresses=os.environ.get("NACOS_SERVER_ADDR"),
namespace=os.environ.get("NACOS_NAMESPACE"),
username=os.environ.get("NACOS_USERNAME"),
password=os.environ.get("NACOS_PASSWORD")
)
# 查看 examples/nacos_example.py 获取最佳实践
```
### 管理器使用
```python
# 创建管理器（以 Nacos 为例）
manager = NexusConfigManager.with_nacos(
server_addresses="localhost:8848",
namespace="production",
username="admin",
password="admin123"
)
# 批量注册配置
configs = [DatabaseConfig, RedisConfig, AppConfig]
for config_class in configs:
manager.register(config_class)
# 获取配置（类型安全）
app_config: AppConfig = manager.get_config(AppConfig)
# 检查管理器状态
info = manager.get_manager_info()
print(f"已注册 {info['registered_configs']} 个配置")
# 优雅关闭
manager.close()
```
### 上下文管理器
```python
# 推荐使用 with 语句，自动管理资源
with NexusConfigManager.with_nacos("localhost:8848") as manager:
manager.register(AppConfig)
app_config = manager.get_config(AppConfig)
print(f"App: {app_config.app_name}")
# 管理器自动关闭，清理所有资源
```
### 配置实时更新
```python
# 配置更新是自动的！
manager.register(AppConfig)
# 在 Nacos 控制台修改配置后...
app_config = manager.get_config(AppConfig) # 自动获取最新配置
# 也支持手动刷新
updated_config = manager.reload_config(AppConfig)
```
## 🧪 扩展新的配置源
YAI Nexus Configuration 的设计让添加新配置源变得非常简单：
```python
from yai_nexus_configuration.providers import AbstractProvider
class MyCustomProvider(AbstractProvider):
def __init__(self, config_url: str):
super().__init__("MyCustom")
self.config_url = config_url
def connect(self):
# 实现连接逻辑
pass
def get_config(self, data_id: str, group: str) -> str:
# 实现配置获取逻辑
pass
def watch_config(self, data_id: str, group: str, callback):
# 实现配置监听逻辑
pass
# ... 其他必须实现的方法
# 在 NexusConfigManager 中添加工厂方法
@classmethod
def with_my_custom(cls, config_url: str) -> "NexusConfigManager":
provider = MyCustomProvider(config_url)
return cls(provider)
```
## 🔍 错误处理
```python
from yai_nexus_configuration import (
ConfigNotRegisteredError,
ConfigValidationError,
ProviderConnectionError
)
try:
manager = NexusConfigManager.with_nacos("localhost:8848")
manager.register(DatabaseConfig)
db_config = manager.get_config(DatabaseConfig)
except ProviderConnectionError as e:
print(f"无法连接到配置源: {e}")
except ConfigValidationError as e:
print(f"配置数据验证失败: {e}")
except ConfigNotRegisteredError as e:
print(f"配置未注册: {e}")
```
## 📦 安装
### 基础安装
```bash
# 最小安装（包含文件和 YAML 支持）
pip install yai-nexus-configuration
```
### 功能扩展安装
```bash
# 安装 Nacos 支持
pip install yai-nexus-configuration[nacos]
# 安装所有功能
pip install yai-nexus-configuration[all]
```
### 开发环境安装
```bash
# 克隆项目
git clone https://github.com/yai-nexus/yai-nexus-configuration.git
cd yai-nexus-configuration
# 安装开发依赖
pip install -r requirements.txt
# 或者使用 pip 安装开发模式
pip install -e ".[dev]"
```
### 快速开始
```bash
# 运行文件配置示例（无外部依赖）
python3 examples/file_example.py
# 运行 Nacos 示例
# 1. 确保 Nacos 服务正在运行，并已按示例文件中的说明创建配置
# 2. 设置环境变量:
# export NACOS_SERVER_ADDR="your_nacos_address:8848"
# export NACOS_NAMESPACE="your_namespace" # (可选)
# export NACOS_USERNAME="nacos" # (可选)
# export NACOS_PASSWORD="nacos" # (可选)
# 3. 运行脚本:
python3 examples/nacos_example.py
```
## 🧑💻 开发
### 运行测试
```bash
# 单元测试
pytest tests/
# 覆盖率测试
pytest --cov=src/yai_nexus_configuration tests/
```
## 🎯 设计哲学
YAI Nexus Configuration 的设计遵循以下原则：
1. **简洁胜过复杂** - API 设计力求简洁直观
2. **显式胜过隐式** - 避免魔法方法，所有行为都是可预测的
3. **面向接口编程** - 通过抽象接口实现高度解耦
4. **失败快速暴露** - 配置错误在启动时就会被发现，而不是运行时
5. **类型安全第一** - 完整的类型提示，让 IDE 和工具更好地帮助开发
## 🤝 贡献
我们欢迎任何形式的贡献！
- 🐛 报告 Bug
- 💡 提出新功能建议
- 📖 改进文档
- 🔧 提交代码改进
请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细的贡献指南。
## 📜 许可证
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
## 🙏 致谢
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 提供优秀的数据验证能力
- [nacos-sdk-python](https://github.com/nacos-group/nacos-sdk-python) - Nacos Python SDK
- 所有为这个项目贡献想法和代码的开发者们
---
⭐ 如果这个项目对您有帮助，请给我们一个 Star！
Raw data
{
"_id": null,
"home_page": null,
"name": "yai-nexus-configuration",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "YAI Team <team@yai.com>",
"keywords": "configuration, config, nacos, apollo, settings, management, dynamic, provider, pydantic",
"author": null,
"author_email": "YAI Team <team@yai.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/14/9928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64/yai_nexus_configuration-0.1.1.tar.gz",
"platform": null,
"description": "# YAI Nexus Configuration\n\n\ud83d\ude80 **\u9ad8\u8d28\u91cf\u7684 Python \u914d\u7f6e\u7ba1\u7406\u5e93** - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u652f\u6301\u591a\u79cd\u914d\u7f6e\u6e90\n\n\n\n\n\n## \ud83c\udfac \u5feb\u901f\u4e0a\u624b (Hello, World!)\n\n\u8fd9\u662f\u4f53\u9a8c `yai-nexus-configuration` \u6838\u5fc3\u529f\u80fd\u7684\u6700\u5feb\u65b9\u5f0f\u3002\u6211\u4eec\u5c06\u901a\u8fc7\u4e00\u4e2a\u5b8c\u6574\u7684\u3001\u53ef\u8fd0\u884c\u7684\u793a\u4f8b\uff0c\u5c55\u793a\u201c**\u5b9a\u4e49 -> \u521b\u5efa -> \u6ce8\u518c -> \u83b7\u53d6**\u201d\u7684\u9ec4\u91d1\u8def\u5f84\u3002\n\n### 1. \u9879\u76ee\u7ed3\u6784\n\n\u9996\u5148\uff0c\u8bf7\u50cf\u8fd9\u6837\u7ec4\u7ec7\u60a8\u7684\u9879\u76ee\u6587\u4ef6\uff1a\n\n```\nyour-project/\n\u251c\u2500\u2500 configs/\n\u2502 \u2514\u2500\u2500 DEFAULT_GROUP/\n\u2502 \u2514\u2500\u2500 app_config.json\n\u2514\u2500\u2500 main.py\n```\n\n### 2. \u521b\u5efa\u914d\u7f6e\u6587\u4ef6\n\n\u5728 `configs/DEFAULT_GROUP/` \u76ee\u5f55\u4e0b\u521b\u5efa\u4e00\u4e2a\u540d\u4e3a `app_config.json` \u7684\u6587\u4ef6\uff0c\u5185\u5bb9\u5982\u4e0b\uff1a\n\n```json\n{\n \"database_url\": \"sqlite:///./test.db\",\n \"retries\": 5,\n \"api_key\": \"a-secret-key-from-environment\"\n}\n```\n> **\u63d0\u793a**: \u5728\u672a\u6765\u7684\u7248\u672c\u4e2d\uff0c\u6211\u4eec\u5c06\u652f\u6301 `${VAR}` \u683c\u5f0f\u7684\u73af\u5883\u53d8\u91cf\u81ea\u52a8\u66ff\u6362\uff0c\u4ee5\u589e\u5f3a\u5b89\u5168\u6027\u3002\n\n### 3. \u7f16\u5199 Python \u4ee3\u7801 (`main.py`)\n\n\u73b0\u5728\uff0c\u521b\u5efa `main.py` \u5e76\u590d\u5236\u4ee5\u4e0b\u4ee3\u7801\u3002\u5b83\u5305\u542b\u4e86\u4f7f\u7528\u672c\u5e93\u7684\u6240\u6709\u6838\u5fc3\u6b65\u9aa4\u3002\n\n```python\nfrom yai_nexus_configuration import NexusConfig, nexus_config, NexusConfigManager\n\n# \u6b65\u9aa4 1: \u5b9a\u4e49\u4e00\u4e2a\u4e0e JSON \u7ed3\u6784\u5339\u914d\u7684\u914d\u7f6e\u7c7b\n# @nexus_config \u88c5\u9970\u5668\u5c06\u7c7b\u4e0e\u914d\u7f6e\u6587\u4ef6\u5173\u8054\u8d77\u6765\n@nexus_config(data_id=\"app_config.json\", group=\"DEFAULT_GROUP\")\nclass AppConfig(NexusConfig):\n database_url: str\n retries: int = 3 # \u60a8\u53ef\u4ee5\u63d0\u4f9b\u9ed8\u8ba4\u503c\n api_key: str\n\n# \u6b65\u9aa4 2: \u4f7f\u7528\u5de5\u5382\u65b9\u6cd5\u521b\u5efa\u7ba1\u7406\u5668\n# `with` \u8bed\u53e5\u80fd\u786e\u4fdd\u8d44\u6e90\u88ab\u6b63\u786e\u7ba1\u7406\u548c\u91ca\u653e\nwith NexusConfigManager.with_file(base_path=\"configs\") as manager:\n # \u6b65\u9aa4 3: \u5411\u7ba1\u7406\u5668\u6ce8\u518c\u60a8\u7684\u914d\u7f6e\u7c7b\n manager.register(AppConfig)\n\n # \u6b65\u9aa4 4: \u4ece\u7ba1\u7406\u5668\u4e2d\u83b7\u53d6\u7c7b\u578b\u5b89\u5168\u7684\u914d\u7f6e\u5b9e\u4f8b\n config = manager.get_config(AppConfig)\n\n# \u6b65\u9aa4 5: \u50cf\u4f7f\u7528\u666e\u901a\u5bf9\u8c61\u4e00\u6837\u4f7f\u7528\u60a8\u7684\u914d\u7f6e\nprint(f\"\u6570\u636e\u5e93 URL: {config.database_url}\")\nprint(f\"\u91cd\u8bd5\u6b21\u6570: {config.retries}\")\nprint(f\"API \u5bc6\u94a5: {config.api_key}\")\n\n# \u8fd0\u884c\u6b64\u811a\u672c\uff0c\u60a8\u5c06\u770b\u5230\u4ece\u6587\u4ef6\u4e2d\u52a0\u8f7d\u5e76\u7ecf\u8fc7\u9a8c\u8bc1\u7684\u914d\u7f6e\uff01\n```\n\n**\u6548\u679c**: \u8fd9\u4e2a\u201c\u9ec4\u91d1\u8def\u5f84\u201d\u793a\u4f8b\u6e05\u6670\u5730\u5c55\u793a\u4e86\u672c\u5e93\u7684\u6838\u5fc3\u8bbe\u8ba1\u601d\u60f3\uff0c\u80fd\u5e2e\u52a9\u60a8\u5feb\u901f\u4e0a\u624b\uff0c\u907f\u514d\u5e38\u89c1\u7684\u4f7f\u7528\u9677\u9631\u3002\n\n---\n\n## \u2728 \u4e3b\u8981\u7279\u6027\n\n- \ud83c\udfaf **\u7b80\u6d01\u4f18\u96c5\u7684 API** - \u91c7\u7528\u5de5\u5382\u6a21\u5f0f\uff0c\u4e00\u884c\u4ee3\u7801\u521b\u5efa\u7ba1\u7406\u5668\n- \ud83d\udd12 **\u7ebf\u7a0b\u5b89\u5168** - \u6240\u6709\u64cd\u4f5c\u90fd\u662f\u7ebf\u7a0b\u5b89\u5168\u7684\uff0c\u9002\u7528\u4e8e\u591a\u7ebf\u7a0b\u73af\u5883\n- \ud83d\udd04 **\u81ea\u52a8\u914d\u7f6e\u66f4\u65b0** - \u5b9e\u65f6\u76d1\u542c\u914d\u7f6e\u6e90\u53d8\u66f4\uff0c\u81ea\u52a8\u66f4\u65b0\u672c\u5730\u914d\u7f6e\n- \ud83e\udde9 **\u53ef\u6269\u5c55\u67b6\u6784** - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u8f7b\u677e\u652f\u6301\u65b0\u7684\u914d\u7f6e\u6e90\n- \u2705 **\u7c7b\u578b\u5b89\u5168** - \u5b8c\u6574\u7684\u7c7b\u578b\u63d0\u793a\u652f\u6301\uff0c\u57fa\u4e8e Pydantic \u6570\u636e\u9a8c\u8bc1\n- \ud83d\udce6 **\u96f6\u4f9d\u8d56\u51b2\u7a81** - \u7cbe\u5fc3\u8bbe\u8ba1\u7684\u4f9d\u8d56\u7ba1\u7406\uff0c\u907f\u514d\u7248\u672c\u51b2\u7a81\n\n## \ud83c\udfd7\ufe0f \u67b6\u6784\u8bbe\u8ba1\n\nYAI Nexus Configuration \u91c7\u7528\u4e86\u7ecf\u8fc7\u6df1\u5ea6\u601d\u8003\u7684 **\u65b9\u6848 E\uff08\u5de5\u5382\u6a21\u5f0f\uff09** \u67b6\u6784\uff1a\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u7528\u6237\u4ee3\u7801 \u2502\u2500\u2500\u2500\u2500\u2502 NexusConfigManager \u2502\u2500\u2500\u2500\u2500\u2502 ConfigStore \u2502\n\u2502 \u2502 \u2502 (\u5de5\u5382 + \u7ba1\u7406) \u2502 \u2502 (\u7ebf\u7a0b\u5b89\u5168\u5b58\u50a8) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u25bc\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 AbstractProvider \u2502\n \u2502 (\u62bd\u8c61\u5c42) \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u25bc \u25bc\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 NacosProvider\u2502 \u2502 \u672a\u6765\u7684Provider\u2502\n \u2502 \u2502 \u2502 (Apollo\u7b49) \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### \u6838\u5fc3\u4f18\u52bf\n\n- **\u9ad8\u5185\u805a\uff0c\u4f4e\u8026\u5408**: Provider \u62bd\u8c61\u5c42\u5b8c\u5168\u9694\u79bb\u4e86\u914d\u7f6e\u6e90\u5b9e\u73b0\n- **\u9762\u5411\u63a5\u53e3\u7f16\u7a0b**: \u6838\u5fc3\u903b\u8f91\u53ea\u4f9d\u8d56\u62bd\u8c61\u63a5\u53e3\uff0c\u4fbf\u4e8e\u6d4b\u8bd5\u548c\u6269\u5c55\n- **\u5de5\u5382\u6a21\u5f0f**: \u63d0\u4f9b\u7b80\u6d01\u7684\u521b\u5efa\u63a5\u53e3\uff0c\u9690\u85cf\u590d\u6742\u7684\u521d\u59cb\u5316\u903b\u8f91\n- **\u5355\u4e00\u804c\u8d23**: \u6bcf\u4e2a\u7ec4\u4ef6\u90fd\u6709\u660e\u786e\u7684\u804c\u8d23\u8fb9\u754c\n\n## \ud83d\udd27 \u652f\u6301\u7684\u914d\u7f6e\u6e90\n\n| \u914d\u7f6e\u6e90 | \u72b6\u6001 | \u5de5\u5382\u65b9\u6cd5 | \u8bf4\u660e |\n|--------|------|----------|------|\n| **Nacos** | \u2705 \u5df2\u652f\u6301 | `NexusConfigManager.with_nacos()` | \u963f\u91cc\u5df4\u5df4\u5f00\u6e90\u7684\u914d\u7f6e\u4e2d\u5fc3 |\n| **Apollo** | \ud83d\udea7 \u89c4\u5212\u4e2d | `NexusConfigManager.with_apollo()` | \u643a\u7a0b\u5f00\u6e90\u7684\u914d\u7f6e\u4e2d\u5fc3 |\n| **Etcd** | \ud83d\udea7 \u89c4\u5212\u4e2d | `NexusConfigManager.with_etcd()` | \u5206\u5e03\u5f0f\u952e\u503c\u5b58\u50a8 |\n| **\u672c\u5730\u6587\u4ef6** | \u2705 \u5df2\u652f\u6301 | `NexusConfigManager.with_file()` | \u672c\u5730 JSON/YAML/ENV \u6587\u4ef6 |\n\n## \ud83d\udcd6 \u8be6\u7ec6\u6587\u6863\n\n### \u6587\u4ef6\u914d\u7f6e\u4f7f\u7528\n\n\u6587\u4ef6\u63d0\u4f9b\u8005\u53ef\u4ee5\u6839\u636e\u6587\u4ef6\u6269\u5c55\u540d\uff08`.json` \u6216 `.yaml`\uff09\u81ea\u52a8\u9009\u62e9\u89e3\u6790\u5668\u3002\n\n**1. \u5b9a\u4e49\u591a\u4e2a\u914d\u7f6e\u7c7b**\n\n```python\nfrom yai_nexus_configuration import NexusConfigManager, NexusConfig, nexus_config\n\n# JSON \u914d\u7f6e\n@nexus_config(data_id=\"app.json\", group=\"DEFAULT_GROUP\")\nclass AppConfig(NexusConfig):\n app_name: str\n debug: bool\n\n# YAML \u914d\u7f6e (\u9700\u8981\u5b89\u88c5 PyYAML)\n@nexus_config(data_id=\"database.yaml\", group=\"PROD\")\nclass DbConfig(NexusConfig):\n host: str\n port: int\n```\n\n**2. \u4f7f\u7528\u540c\u4e00\u4e2a\u7ba1\u7406\u5668**\n\n```python\n# \u53ea\u9700\u8981\u4e00\u4e2a\u7ba1\u7406\u5668\u5b9e\u4f8b\nwith NexusConfigManager.with_file(\n base_path=\"configs\", # \u914d\u7f6e\u6587\u4ef6\u6839\u76ee\u5f55\n watch_interval=1.0, # \u6587\u4ef6\u76d1\u542c\u95f4\u9694\uff08\u79d2\uff09\n) as manager:\n \n # \u4f60\u7684\u6587\u4ef6\u7ed3\u6784:\n # configs/\n # \u251c\u2500\u2500 DEFAULT_GROUP/\n # \u2502 \u2514\u2500\u2500 app.json\n # \u2514\u2500\u2500 PROD/\n # \u2514\u2500\u2500 database.yaml\n\n # \u6279\u91cf\u6ce8\u518c\n manager.register(AppConfig, DbConfig)\n \n # \u83b7\u53d6\u914d\u7f6e\n app_config = manager.get_config(AppConfig)\n db_config = manager.get_config(DbConfig)\n \n print(f\"\u5e94\u7528: {app_config.app_name}, \u6570\u636e\u5e93\u4e3b\u673a: {db_config.host}\")\n```\n\n### Nacos \u914d\u7f6e\u4f7f\u7528\n\n```python\n# \u521b\u5efa\u7ba1\u7406\u5668\uff08\u5efa\u8bae\u4ece\u73af\u5883\u53d8\u91cf\u83b7\u53d6\u654f\u611f\u4fe1\u606f\uff09\nmanager = NexusConfigManager.with_nacos(\n server_addresses=os.environ.get(\"NACOS_SERVER_ADDR\"),\n namespace=os.environ.get(\"NACOS_NAMESPACE\"),\n username=os.environ.get(\"NACOS_USERNAME\"),\n password=os.environ.get(\"NACOS_PASSWORD\")\n)\n\n# \u67e5\u770b examples/nacos_example.py \u83b7\u53d6\u6700\u4f73\u5b9e\u8df5\n```\n\n### \u7ba1\u7406\u5668\u4f7f\u7528\n\n```python\n# \u521b\u5efa\u7ba1\u7406\u5668\uff08\u4ee5 Nacos \u4e3a\u4f8b\uff09\nmanager = NexusConfigManager.with_nacos(\n server_addresses=\"localhost:8848\",\n namespace=\"production\",\n username=\"admin\",\n password=\"admin123\"\n)\n\n# \u6279\u91cf\u6ce8\u518c\u914d\u7f6e\nconfigs = [DatabaseConfig, RedisConfig, AppConfig]\nfor config_class in configs:\n manager.register(config_class)\n\n# \u83b7\u53d6\u914d\u7f6e\uff08\u7c7b\u578b\u5b89\u5168\uff09\napp_config: AppConfig = manager.get_config(AppConfig)\n\n# \u68c0\u67e5\u7ba1\u7406\u5668\u72b6\u6001\ninfo = manager.get_manager_info()\nprint(f\"\u5df2\u6ce8\u518c {info['registered_configs']} \u4e2a\u914d\u7f6e\")\n\n# \u4f18\u96c5\u5173\u95ed\nmanager.close()\n```\n\n### \u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\n\n```python\n# \u63a8\u8350\u4f7f\u7528 with \u8bed\u53e5\uff0c\u81ea\u52a8\u7ba1\u7406\u8d44\u6e90\nwith NexusConfigManager.with_nacos(\"localhost:8848\") as manager:\n manager.register(AppConfig)\n \n app_config = manager.get_config(AppConfig)\n print(f\"App: {app_config.app_name}\")\n \n# \u7ba1\u7406\u5668\u81ea\u52a8\u5173\u95ed\uff0c\u6e05\u7406\u6240\u6709\u8d44\u6e90\n```\n\n### \u914d\u7f6e\u5b9e\u65f6\u66f4\u65b0\n\n```python\n# \u914d\u7f6e\u66f4\u65b0\u662f\u81ea\u52a8\u7684\uff01\nmanager.register(AppConfig)\n\n# \u5728 Nacos \u63a7\u5236\u53f0\u4fee\u6539\u914d\u7f6e\u540e...\napp_config = manager.get_config(AppConfig) # \u81ea\u52a8\u83b7\u53d6\u6700\u65b0\u914d\u7f6e\n\n# \u4e5f\u652f\u6301\u624b\u52a8\u5237\u65b0\nupdated_config = manager.reload_config(AppConfig)\n```\n\n## \ud83e\uddea \u6269\u5c55\u65b0\u7684\u914d\u7f6e\u6e90\n\nYAI Nexus Configuration \u7684\u8bbe\u8ba1\u8ba9\u6dfb\u52a0\u65b0\u914d\u7f6e\u6e90\u53d8\u5f97\u975e\u5e38\u7b80\u5355\uff1a\n\n```python\nfrom yai_nexus_configuration.providers import AbstractProvider\n\nclass MyCustomProvider(AbstractProvider):\n def __init__(self, config_url: str):\n super().__init__(\"MyCustom\")\n self.config_url = config_url\n \n def connect(self):\n # \u5b9e\u73b0\u8fde\u63a5\u903b\u8f91\n pass\n \n def get_config(self, data_id: str, group: str) -> str:\n # \u5b9e\u73b0\u914d\u7f6e\u83b7\u53d6\u903b\u8f91\n pass\n \n def watch_config(self, data_id: str, group: str, callback):\n # \u5b9e\u73b0\u914d\u7f6e\u76d1\u542c\u903b\u8f91\n pass\n \n # ... \u5176\u4ed6\u5fc5\u987b\u5b9e\u73b0\u7684\u65b9\u6cd5\n\n# \u5728 NexusConfigManager \u4e2d\u6dfb\u52a0\u5de5\u5382\u65b9\u6cd5\n@classmethod\ndef with_my_custom(cls, config_url: str) -> \"NexusConfigManager\":\n provider = MyCustomProvider(config_url)\n return cls(provider)\n```\n\n## \ud83d\udd0d \u9519\u8bef\u5904\u7406\n\n```python\nfrom yai_nexus_configuration import (\n ConfigNotRegisteredError,\n ConfigValidationError,\n ProviderConnectionError\n)\n\ntry:\n manager = NexusConfigManager.with_nacos(\"localhost:8848\")\n manager.register(DatabaseConfig)\n db_config = manager.get_config(DatabaseConfig)\n \nexcept ProviderConnectionError as e:\n print(f\"\u65e0\u6cd5\u8fde\u63a5\u5230\u914d\u7f6e\u6e90: {e}\")\n \nexcept ConfigValidationError as e:\n print(f\"\u914d\u7f6e\u6570\u636e\u9a8c\u8bc1\u5931\u8d25: {e}\")\n \nexcept ConfigNotRegisteredError as e:\n print(f\"\u914d\u7f6e\u672a\u6ce8\u518c: {e}\")\n```\n\n## \ud83d\udce6 \u5b89\u88c5\n\n### \u57fa\u7840\u5b89\u88c5\n\n```bash\n# \u6700\u5c0f\u5b89\u88c5\uff08\u5305\u542b\u6587\u4ef6\u548c YAML \u652f\u6301\uff09\npip install yai-nexus-configuration\n```\n\n### \u529f\u80fd\u6269\u5c55\u5b89\u88c5\n\n```bash\n# \u5b89\u88c5 Nacos \u652f\u6301\npip install yai-nexus-configuration[nacos]\n\n# \u5b89\u88c5\u6240\u6709\u529f\u80fd\npip install yai-nexus-configuration[all]\n```\n\n### \u5f00\u53d1\u73af\u5883\u5b89\u88c5\n\n```bash\n# \u514b\u9686\u9879\u76ee\ngit clone https://github.com/yai-nexus/yai-nexus-configuration.git\ncd yai-nexus-configuration\n\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\npip install -r requirements.txt\n\n# \u6216\u8005\u4f7f\u7528 pip \u5b89\u88c5\u5f00\u53d1\u6a21\u5f0f\npip install -e \".[dev]\"\n```\n\n### \u5feb\u901f\u5f00\u59cb\n\n```bash\n# \u8fd0\u884c\u6587\u4ef6\u914d\u7f6e\u793a\u4f8b\uff08\u65e0\u5916\u90e8\u4f9d\u8d56\uff09\npython3 examples/file_example.py\n\n# \u8fd0\u884c Nacos \u793a\u4f8b\n# 1. \u786e\u4fdd Nacos \u670d\u52a1\u6b63\u5728\u8fd0\u884c\uff0c\u5e76\u5df2\u6309\u793a\u4f8b\u6587\u4ef6\u4e2d\u7684\u8bf4\u660e\u521b\u5efa\u914d\u7f6e\n# 2. \u8bbe\u7f6e\u73af\u5883\u53d8\u91cf:\n# export NACOS_SERVER_ADDR=\"your_nacos_address:8848\"\n# export NACOS_NAMESPACE=\"your_namespace\" # (\u53ef\u9009)\n# export NACOS_USERNAME=\"nacos\" # (\u53ef\u9009)\n# export NACOS_PASSWORD=\"nacos\" # (\u53ef\u9009)\n# 3. \u8fd0\u884c\u811a\u672c:\npython3 examples/nacos_example.py\n```\n\n## \ud83e\uddd1\u200d\ud83d\udcbb \u5f00\u53d1\n\n### \u8fd0\u884c\u6d4b\u8bd5\n\n```bash\n# \u5355\u5143\u6d4b\u8bd5\npytest tests/\n\n# \u8986\u76d6\u7387\u6d4b\u8bd5\npytest --cov=src/yai_nexus_configuration tests/\n```\n\n## \ud83c\udfaf \u8bbe\u8ba1\u54f2\u5b66\n\nYAI Nexus Configuration \u7684\u8bbe\u8ba1\u9075\u5faa\u4ee5\u4e0b\u539f\u5219\uff1a\n\n1. **\u7b80\u6d01\u80dc\u8fc7\u590d\u6742** - API \u8bbe\u8ba1\u529b\u6c42\u7b80\u6d01\u76f4\u89c2\n2. **\u663e\u5f0f\u80dc\u8fc7\u9690\u5f0f** - \u907f\u514d\u9b54\u6cd5\u65b9\u6cd5\uff0c\u6240\u6709\u884c\u4e3a\u90fd\u662f\u53ef\u9884\u6d4b\u7684\n3. **\u9762\u5411\u63a5\u53e3\u7f16\u7a0b** - \u901a\u8fc7\u62bd\u8c61\u63a5\u53e3\u5b9e\u73b0\u9ad8\u5ea6\u89e3\u8026\n4. **\u5931\u8d25\u5feb\u901f\u66b4\u9732** - \u914d\u7f6e\u9519\u8bef\u5728\u542f\u52a8\u65f6\u5c31\u4f1a\u88ab\u53d1\u73b0\uff0c\u800c\u4e0d\u662f\u8fd0\u884c\u65f6\n5. **\u7c7b\u578b\u5b89\u5168\u7b2c\u4e00** - \u5b8c\u6574\u7684\u7c7b\u578b\u63d0\u793a\uff0c\u8ba9 IDE \u548c\u5de5\u5177\u66f4\u597d\u5730\u5e2e\u52a9\u5f00\u53d1\n\n## \ud83e\udd1d \u8d21\u732e\n\n\u6211\u4eec\u6b22\u8fce\u4efb\u4f55\u5f62\u5f0f\u7684\u8d21\u732e\uff01\n\n- \ud83d\udc1b \u62a5\u544a Bug\n- \ud83d\udca1 \u63d0\u51fa\u65b0\u529f\u80fd\u5efa\u8bae \n- \ud83d\udcd6 \u6539\u8fdb\u6587\u6863\n- \ud83d\udd27 \u63d0\u4ea4\u4ee3\u7801\u6539\u8fdb\n\n\u8bf7\u67e5\u770b [CONTRIBUTING.md](CONTRIBUTING.md) \u4e86\u89e3\u8be6\u7ec6\u7684\u8d21\u732e\u6307\u5357\u3002\n\n## \ud83d\udcdc \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1 - \u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\u3002\n\n## \ud83d\ude4f \u81f4\u8c22\n\n- [Pydantic](https://pydantic-docs.helpmanual.io/) - \u63d0\u4f9b\u4f18\u79c0\u7684\u6570\u636e\u9a8c\u8bc1\u80fd\u529b\n- [nacos-sdk-python](https://github.com/nacos-group/nacos-sdk-python) - Nacos Python SDK\n- \u6240\u6709\u4e3a\u8fd9\u4e2a\u9879\u76ee\u8d21\u732e\u60f3\u6cd5\u548c\u4ee3\u7801\u7684\u5f00\u53d1\u8005\u4eec\n\n---\n\n\u2b50 \u5982\u679c\u8fd9\u4e2a\u9879\u76ee\u5bf9\u60a8\u6709\u5e2e\u52a9\uff0c\u8bf7\u7ed9\u6211\u4eec\u4e00\u4e2a Star\uff01\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u9ad8\u8d28\u91cf\u7684 Python \u914d\u7f6e\u7ba1\u7406\u5e93 - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u652f\u6301\u591a\u79cd\u914d\u7f6e\u6e90",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/yai-team/yai-nexus-configuration/issues",
"Changelog": "https://github.com/yai-team/yai-nexus-configuration/blob/main/CHANGELOG.md",
"Documentation": "https://yai-nexus-configuration.readthedocs.io/",
"Homepage": "https://github.com/yai-team/yai-nexus-configuration",
"Repository": "https://github.com/yai-team/yai-nexus-configuration.git"
},
"split_keywords": [
"configuration",
" config",
" nacos",
" apollo",
" settings",
" management",
" dynamic",
" provider",
" pydantic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ebd05ee4abf2606273f7ea0032b0ddc6d265f8540308118fe17322cb787c7216",
"md5": "9c642ab276808e3c4a831f934fe767eb",
"sha256": "b5369c74f58deb59b50458cae121279620bc967bbe51662ee8418a89a8380267"
},
"downloads": -1,
"filename": "yai_nexus_configuration-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c642ab276808e3c4a831f934fe767eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25783,
"upload_time": "2025-07-08T10:33:33",
"upload_time_iso_8601": "2025-07-08T10:33:33.185287Z",
"url": "https://files.pythonhosted.org/packages/eb/d0/5ee4abf2606273f7ea0032b0ddc6d265f8540308118fe17322cb787c7216/yai_nexus_configuration-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d0149928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64",
"md5": "1e70e17d0b5437cd3e03ed4fe6e66b5f",
"sha256": "4231370e2a2dafcb41cede3bf9c0d2a93a4ed97d9f55776371ddfa2285e06716"
},
"downloads": -1,
"filename": "yai_nexus_configuration-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1e70e17d0b5437cd3e03ed4fe6e66b5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24967,
"upload_time": "2025-07-08T10:33:34",
"upload_time_iso_8601": "2025-07-08T10:33:34.256341Z",
"url": "https://files.pythonhosted.org/packages/d0/14/9928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64/yai_nexus_configuration-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 10:33:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yai-team",
"github_project": "yai-nexus-configuration",
"github_not_found": true,
"lcname": "yai-nexus-configuration"
}
JSON
