Python/FastAPI中JSON返回图片URL列表的实现与规范

1. 现有代码修改方法 #

你当前返回结构错误的核心原因是：将所有图片URL通过逗号拼接成了单个长字符串，再把这个长字符串作为唯一元素放进数组，才会出现单元素包含多个地址的问题。两种目标格式的修改方式如下：

格式1：纯字符串URL数组 #

直接删除字符串拼接逻辑，把遍历生成的URL列表直接赋值给imgs_url字段即可。
关键修改代码：

# 遍历文件生成fileList的逻辑保持不变，删除下面这行拼接代码
# file_urls = ", ".join(fileList)

new_item = Product(
    name=name,
    price=price,
    description=description,
    imgs_url=fileList, # 直接传入URL列表，无需额外包装
    owner_id=current_user.id
)

注意：使用该格式需要将数据库中imgs_url字段调整为对应数组类型：PostgreSQL可使用ARRAY(TEXT)类型，MySQL 5.7+可使用JSON类型存储数组。

格式2：带url字段的对象数组 #

在生成URL列表后，做一层简单的格式转换，将每个URL包装为带url属性的字典即可。
关键修改代码：

# 遍历文件生成fileList的逻辑保持不变，新增格式转换逻辑
file_url_objs = [{"url": single_url} for single_url in fileList]

new_item = Product(
    name=name,
    price=price,
    description=description,
    imgs_url=file_url_objs, # 传入转换后的对象数组
    owner_id=current_user.id
)

注意：使用该格式需要将数据库中imgs_url字段调整为JSON/JSONB类型，不支持用普通字符串或字符串数组类型存储。

2. 两种格式的选型建议 #

没有绝对的对错，按业务场景选即可：

• 优先选纯字符串数组的场景：如果图片资源只需要返回访问地址，短期没有扩展其他属性（比如图片宽高、文件大小、是否封面、缩略图地址、审核状态）的计划，选纯字符串数组是更优方案：
  • 结构更简洁，传输体积更小
  • 前后端解析成本更低，不需要额外读取对象属性
  • 存储冗余更少，缓存和数据库占用空间更低
• 选对象数组的场景：如果后续确定要给图片扩展除地址外的其他属性，直接选对象数组格式，扩展性更强，后续新增字段不需要改动接口结构，不会破坏已有前端的兼容性。

你当前使用的「多URL拼接为单字符串存入数组」的写法属于反模式，前端需要额外做字符串分割才能拿到单个地址，极易出现解析bug，无论选上述哪种格式都需要废弃该写法。

3. 图片URL列表的通用行业约定 #

目前没有强制的ISO级标准，但Web开发领域有普遍遵守的实践约定：

• 仅返回单一属性的同类资源列表时，优先使用基础类型数组（即字符串数组存URL），这是RESTful接口设计的通用惯例
• 当资源本身包含多个属性时，使用对象数组，URL作为对象的必填字段，字段名通用命名为url，少数前端场景会用src，但url的跨端认知成本最低
• 带分页的图片列表会在外层增加分页元数据（总数、页码、分页大小），但列表内单条图片数据的格式遵循上述规则
• 禁止将多个同类型值拼接为单个字符串存储在结构化数据中，该写法会大幅增加联调成本和解析出错概率。

内容的提问来源于stack exchange，提问作者pythonGo