单体转Python微服务项目中共享代码的结构与构建方案问询

我之前也踩过类似的坑——从单体转微服务初期，想在单仓里统一管所有服务和共享代码，既不想搞复杂的pip包发布或git子模块，又不想复制代码（毕竟后期改一处要同步N份，维护起来太糟心），分享几个亲测好用的实操方案给你：

方案一：基于Docker构建上下文复用共享代码 #

这其实就是你正在尝试的方向，只要把Dockerfile的细节补全，就能完美实现单仓内代码复用：

1. 调整docker-compose的构建配置 #

把每个服务的构建上下文设为项目根目录，这样Docker能访问到repo里的所有文件，docker-compose.yaml可以这么写：

services:
  service1:
    build:
      context: .
      dockerfile: ./service1/Dockerfile
    command: python Code/manage.py runserver 0.0.0.0:8000
    # 开发环境可选挂载本地目录实现热重载，不用每次改代码都重构镜像
    # volumes:
    #   - ./service1/Code:/app/Code
    #   - ./utils:/app/utils
  service2:
    build:
      context: .
      dockerfile: ./service2/Dockerfile
    # 同理配置service2的启动命令等

2. 优化每个服务的Dockerfile #

以service1为例，我们只复制必要的代码，再通过PYTHONPATH让Python能识别共享模块：

# 用你项目对应的Python版本镜像
FROM python:3.11-slim

# 设定容器内的工作目录
WORKDIR /app

# 先复制共享的utils目录到容器内
COPY ./utils /app/utils
# 再复制service1的业务代码
COPY ./service1/Code /app/Code
# 复制service1的依赖清单（如果有的话）
COPY ./service1/requirements.txt .

# 安装服务依赖
RUN pip install --no-cache-dir -r requirements.txt

# 关键：设置Python路径，让Python能直接import utils里的模块
ENV PYTHONPATH=/app

# 启动服务
CMD ["python", "Code/manage.py", "runserver", "0.0.0.0:8000"]

3. 必做：配置根目录的.dockerignore #

一定要在项目根目录建这个文件，避免把无关文件（比如git文件、虚拟环境）拖进构建上下文，拖慢构建速度：

.git
.gitignore
.venv
__pycache__
*.pyc
*.pyo
.env
.vscode

方案二：本地开发与镜像构建统一复用逻辑 #

本地开发时不用每次都构建镜像，直接通过设置PYTHONPATH让本地Python识别utils：

• Linux/macOS终端运行：

  export PYTHONPATH=/path/to/your/repo/root
  cd service1/Code
  python manage.py runserver 0.0.0.0:8000
  

• Windows环境可以用：

  set PYTHONPATH=C:\path\to\your\repo\root
  cd service1\Code
  python manage.py runserver 0.0.0.0:8000
  

这样本地开发和Docker镜像里的代码引用逻辑完全一致，不会出现“本地能跑，镜像里报错”的尴尬。

关于你的其他顾虑 #

• 为什么不复制代码？谷歌那个demo里的代码复制虽然简单，但后期utils改一处要同步N个服务的复制版本，完全是维护噩梦，你的思路完全正确——要从根源避免重复代码。
• 什么时候要转独立包？等你的utils功能稳定、被更多服务依赖，或者需要单独迭代发布的时候，再把它抽成私有pip包或git依赖都不迟，初期单仓复用是最高效的迭代方式。

有没有参考的示例结构？ #

虽然没有完全和你目标结构一致的公开repo，但很多内部的单仓微服务项目都是这么玩的——核心就是用Docker构建上下文把共享代码纳入构建流程，再通过Python路径实现模块复用。你可以先基于上面的方案搭起来，后续再根据需求调整。

备注：内容来源于stack exchange，提问作者NEB