第一个项目踩坑记录（用于后续复习）

本文核心目的：记录自己第一个项目开发过程中踩过的各类坑，梳理问题原因和解决方案/注意事项，方便后续复习回顾，避免重复踩坑。

一、巧用环境变量，规避环境切换报错

学习阶段很少使用环境变量，总觉得多写一遍配置过于繁琐，习惯直接使用写死的变量。但实际工作中，项目需经历「开发环境→测试环境→预生产环境→生产环境」的多环境切换，不同环境对应的数据库地址、外部接口地址等均不相同。

若依赖手动逐一修改写死的变量，极易遗漏某个隐藏在代码角落的配置，导致环境切换后报错、出现未知bug。

补充注意事项：环境变量的命名必须规范、统一。例如数据库名称统一命名为DB_NAME，避免使用杂乱无章、含义模糊的命名，降低后续维护和排查成本。

二、巧用多线程，解决实际开发中的性能与超时问题

学习阶段遇到的需求，大多可通过单线程实现，但实际项目开发中，很多场景单线程无法满足需求，需借助多线程完成。

典型场景：接收外部接口传入的数据后，需进行复杂处理再返回结果。此时需采用异步操作，先响应外部请求，再通过异步回调处理数据并反馈给对方，否则会导致对方请求超时。这种场景下，就需要引入多线程和队列相关知识。

本次项目实践：使用「生产者-消费者模型」，实现接口与耗时任务的解耦，让接口能够立即返回响应，避免请求超时；同时通过设置队列容量和消费并发数，实现削峰填谷，应对短时间内接收大量数据的场景——接收数据后先立即响应，再将处理任务加入队列，由消费者线程逐一处理，提升效率且避免拥堵。

结合FastAPI核心知识点，梳理单线程、多线程、队列的核心用法（重点复习）：

• FastAPI的线程模型：async def（单线程异步协程），适合纯IO操作，禁止写入阻塞代码；def（自动启用多线程），适合同步IO操作，开发成本低；异步代码中调用同步代码，需使用asyncio.to_thread()。

• 队列的核心价值：在FastAPI中实现「生产者-消费者模型」，解耦接口与耗时任务，避免请求超时；通过队列容量和消费并发数，实现削峰填谷，应对高并发场景。

• 场景选型：

  • 单实例、轻量后台任务：使用queue.Queue + 多线程，简单易用、成本低；

  • CPU密集型任务：使用multiprocessing.Queue + 多进程，绕开Python GIL锁，提升处理效率；

  • 多实例部署、生产环境：使用Redis/RabbitMQ + Celery，实现分布式任务调度，支持定时任务、失败重试等高级功能。

三、数据库规范定义，避免隐藏bug

学习阶段定义数据库时，往往忽略细节规范，容易导致后续出现意想不到的报错。例如，创建的多张表，表头的字符集、字符序列不一致，会导致表之间无法进行join操作、无法正常对比数据等问题（本次项目已踩此坑，核心原因是建表时未明确规范字符集和字符序列）。

四、数据库命名规范，遵守行业标准

此问题警示：任何操作前，需先明确对应标准，不可想当然开发。本次项目中，初期想当然地使用中文作为数据库名称和表名，遭到运维提醒——行业内几乎没有用中文命名数据库的情况，后续查阅数据库规范发现，中文命名会引发各类编码问题。

核心结论（重点复习）：数据库/表名不建议使用中文，行业通用规范仅支持「纯英文 + 数字 + 下划线」（数字不能作为开头）。这并非技术能否实现的问题，而是关乎生产环境的兼容性、可维护性和稳定性，具体原因及特殊情况如下：

1. 技术上可实现，但存在致命隐患：主流数据库（MySQL/PG/Oracle）虽支持中文命名，但需配置数据库字符集（如utf8mb4），且必须用反引号`（MySQL）、双引号（PG）包裹（如CREATE DATABASE 电商;/CREATE TABLE 用户;），实际使用中踩坑无数：

   1. 跨环境/工具兼容问题：部分数据库客户端、备份工具、ORM框架（如SQLAlchemy）对中文命名支持不佳，易出现乱码、识别失败；

   2. 命令行/脚本执行报错：服务器终端若未配置中文编码，执行含中文的SQL脚本会直接乱码，导致建库、建表失败；

   3. 团队协作混乱：中文存在同音字、繁体/简体差异，易出现命名不一致（如订单/定单），远不如英文语义统一；

   4. 跨库迁移麻烦：不同数据库对中文命名的解析规则不同，后续进行跨数据库迁移（如MySQL→PG）时，会出现大量兼容问题。

2. 唯一例外：仅个人本地临时测试时，可临时使用中文命名；生产、开发、测试等团队共享环境，绝对禁止使用中文命名。即便涉及专属业务名词，也需使用拼音全拼或英文翻译（如gonggao→announcement、dingdan→order）。

五、接口自检查，降低联调成本

与外部进行接口联调前，需先自行检查接口可用性，排查潜在异常。建议通过mock模拟数据，使用Postman等工具对自身接口进行全面测试，确保接口能够正常跑通、无异常后，再与对方进行联调，避免联调时因自身接口问题浪费双方时间。

六、传输数据留存，便于报错排查

在接收外部传入数据、向外部发送数据的节点，建议将数据打印输出，或保存为日志文件。若后续出现报错，可通过留存的传输数据快速定位问题原因，避免因无数据追溯而无法排查报错根源，减少问题解决时间。

七、接口字段定义规范，提升交互效率

接口字段命名需规范统一，便于与对接方高效协作。建议采用驼峰命名法（如user_name对应传输字段userName），避免命名混乱导致的对接失误。

八、数据保存方式，适配部署需求

开发阶段，可能习惯使用.json格式保存服务数据，这种方式在本地开发时便捷可行，但不适用于Docker打包部署场景——每次更新部署时，json配置文件会丢失，导致数据丢失。

正确做法：将数据保存到数据库中，无论后续如何进行Docker打包、更新部署，数据库中的数据不会丢失，配置信息可长期留存，保障项目稳定性。