Python 项目结构最佳实践：配置、请求、业务分开写，后期真的省事

适合个人开发者、AI 工具作者、脚本自动化玩家。如果你现在的项目还把 API Key、请求逻辑、业务逻辑全写在一个文件里这篇文章可以直接改掉你的写法。为什么项目一开始就要拆结构很多人做项目的时候第一版通常都很简单一个main.py里面直接写请求Key 也写死在里面业务逻辑和接口调用混在一起这种写法能跑但很快就会出现问题代码越来越乱修改一个地方要翻很多行换模型、换接口、换配置都很麻烦出错后不好排查所以如果你做的是 AI 工具、自动化脚本、API 接入项目最好从一开始就把结构拆开。这篇文章直接给你一个适合个人开发者的最小结构方案。一、先说结论推荐的项目结构你可以把项目拆成这几块project/ ├── .env ├── config.py ├── llm_client.py ├── main.py ├── requirements.txt └── logs/每个文件干什么.env放密钥、地址、模型名config.py统一读取配置llm_client.py封装 API 调用main.py写业务逻辑logs/放日志这种结构不复杂但后期很好维护。二、为什么不建议把所有代码写在一个文件里1. 维护麻烦你一旦把 API 调用、错误处理、业务逻辑、配置读取全写在一起后面改起来会很痛苦。2. 不方便复用如果你以后还想做第二个项目很多代码没法直接拿过来。3. 不利于排错出问题时你根本不容易判断是配置错了还是请求错了还是业务逻辑错了。4. 不适合扩展你后面一旦加重试、缓存、日志、限流这种单文件结构会越来越乱。三、.env里放什么最合适建议把这些放进去API_KEY*** BASE_URLhttps://your-api-domain.com/v1 MODELyour-model-name TIMEOUT20 MAX_RETRIES3这样做的好处不把敏感信息写死在代码里本地和线上可以切换配置修改参数时不用动业务代码四、config.py怎么写config.py的作用就是统一读取配置并做校验。importosfromdotenvimportload_dotenv load_dotenv()defget_config():api_keyos.getenv(API_KEY)base_urlos.getenv(BASE_URL)modelos.getenv(MODEL)timeoutint(os.getenv(TIMEOUT,20))max_retriesint(os.getenv(MAX_RETRIES,3))ifnotapi_key:raiseValueError(API_KEY is required)ifnotbase_url:raiseValueError(BASE_URL is required)ifnotmodel:raiseValueError(MODEL is required)return{api_key:api_key,base_url:base_url,model:model,timeout:timeout,max_retries:max_retries,}这个文件的作用统一读取环境变量启动时提前发现问题避免 Key 为空还继续跑五、llm_client.py怎么封装最舒服这里建议把所有 API 调用都放在一个地方。importtimefromopenaiimportOpenAIfromopenaiimportAPIError,APIConnectionError,APITimeoutError,RateLimitErrorfromconfigimportget_config configget_config()clientOpenAI(api_keyconfig[api_key],base_urlconfig[base_url],timeoutfloat(config[timeout]),)defask_llm(prompt:str)-str:last_errorNoneforattemptinrange(1,config[max_retries]1):try:responseclient.chat.completions.create(modelconfig[model],messages[{role:system,content:你是一个专业的技术助手。},{role:user,content:prompt},],)returnresponse.choices[0].message.contentexcept(APIConnectionError,APITimeoutError,RateLimitError,APIError)ase:last_erroreifattemptconfig[max_retries]:wait2*attemptprint(f第{attempt}次失败{wait}秒后重试{e})time.sleep(wait)else:print(f重试结束最终失败{e})raiseRuntimeError(f请求失败{last_error})为什么这样封装因为你后面只要改这个文件就能影响整个项目的调用行为。六、main.py只负责业务逻辑main.py不要再管配置不要再管重试不要再管细节调用。fromllm_clientimportask_llmdefmain():question给我写一个 Flask 接口示例answerask_llm(question)print(answer)if__name____main__:main()这样写的好处主入口非常清楚业务逻辑和基础设施分离后面加更多功能也不乱七、这套结构适合哪些项目特别适合这些场景AI 工具站自动化脚本Agent 工作流文本生成项目个人效率工具技术副业项目如果你后面还打算继续迭代这种拆法会比单文件强很多。八、几个很容易踩坑的地方1. 不要把 Key 写死在代码里一定放.env。2. 不要把请求逻辑散落在各处统一封装到一个文件里。3. 不要把业务和基础设施混在一起main.py只做流程控制。4. 不要忘了做配置校验启动时报错总比运行半天才发现问题好。九、如果你后面要扩展还可以继续加什么当项目变大后你还可以继续加logger.py统一日志cache.py缓存结果retry.py单独抽重试逻辑api/不同接口模块化tests/测试用例但对于个人开发者来说先把上面这套最小结构跑通就够了。十、结语很多项目后面不好维护不是因为功能太复杂而是一开始就把所有东西写在一起。如果你能从第一天就把配置请求业务日志分开处理后面会省很多时间。如果你也在做 AI 工具、脚本自动化或者个人项目可以留言或私信我可以把我整理好的项目模板发给你。免责声明本文内容仅用于技术交流与经验分享不构成任何商业承诺。具体使用效果请以实际测试为准。