在Python项目开发中，我们经常会通过环境变量传递端口号、重试次数等数值型配置，这些环境变量默认都是字符串类型，需要转换为整数才能正常使用。如果直接进行类型转换，很容易因为环境变量不存在、值不是合法数字等问题导致程序崩溃，同时配合类型注解能让代码的类型约束更清晰，减少后续维护的问题。
基础转换的问题
很多开发者会直接使用int()函数转换环境变量，这种方式存在明显的风险：
- 如果环境变量不存在，
os.getenv会返回None，直接传入int()会抛出TypeError - 如果环境变量的值是空字符串或者非数字字符串，会抛出
ValueError - 没有类型注解的话，其他开发者无法直观知道这个变量最终的类型
下面是错误示例：
import os
# 风险写法，没有异常处理和类型注解
port = int(os.getenv("APP_PORT"))
安全的转换方案
添加异常处理和默认值
我们可以通过捕获异常的方式处理转换失败的场景，同时给环境变量设置合理的默认值，保证程序在配置缺失时也能正常运行。
import os
def safe_env_to_int(env_name: str, default: int = 0) -> int:
"""安全将环境变量转换为整数
:param env_name: 环境变量名称
:param default: 转换失败时的默认返回值
:return: 转换后的整数或默认值
"""
value = os.getenv(env_name)
if value is None:
return default
try:
return int(value)
except ValueError:
# 值不是合法数字时返回默认值
return default
# 使用示例，类型注解明确返回值是int类型
app_port: int = safe_env_to_int("APP_PORT", 8080)
retry_count: int = safe_env_to_int("RETRY_COUNT", 3)
严格模式的可选实现
如果某些环境变量是必须的，不允许使用默认值，我们可以实现一个严格模式的转换函数，转换失败时直接抛出异常，让问题在启动阶段就暴露出来。
import os
def strict_env_to_int(env_name: str) -> int:
"""严格模式将环境变量转换为整数，转换失败直接抛出异常
:param env_name: 环境变量名称
:return: 转换后的整数
:raises ValueError: 环境变量不存在或值不是合法数字时抛出
"""
value = os.getenv(env_name)
if value is None:
raise ValueError(f"环境变量 {env_name} 不存在")
return int(value)
# 使用示例，必须保证环境变量存在且合法
db_port: int = strict_env_to_int("DB_PORT")
类型注解的注意事项
类型注解不会影响程序的运行逻辑，但是能配合类型检查工具（如mypy）提前发现类型错误，提升代码的可靠性。需要注意以下几点：
- 函数参数和返回值都要添加明确的类型注解，比如上面的
env_name: str和-> int - 变量赋值时也可以添加类型注解，比如
app_port: int = ...，明确变量的预期类型 - 不要给转换函数返回
Optional[int]类型，除非你确实允许返回None，否则会让类型约束变得模糊
实际场景使用示例
下面是一个完整的配置读取示例，结合安全转换和类型注解，适合在Web项目或者后台服务中使用：
import os
from typing import Dict
def safe_env_to_int(env_name: str, default: int = 0) -> int:
"""安全将环境变量转换为整数"""
value = os.getenv(env_name)
if value is None:
return default
try:
return int(value)
except ValueError:
return default
# 配置类，所有配置项都有明确的类型注解
class AppConfig:
def __init__(self) -> None:
self.port: int = safe_env_to_int("APP_PORT", 8080)
self.max_connections: int = safe_env_to_int("MAX_CONNECTIONS", 100)
self.retry_interval: int = safe_env_to_int("RETRY_INTERVAL", 5)
# 初始化配置
config: AppConfig = AppConfig()
print(f"服务端口: {config.port}")
print(f"最大连接数: {config.max_connections}")
这种写法既保证了环境变量转换的安全性，又通过类型注解让配置项的类型一目了然，后续修改或者扩展配置时也不容易出现类型相关的错误。