后端接口的“一鱼两吃”：如何优雅复用后台 API 适配小程序？

能够将一个后台接口优雅地复用，并适配小程序端的无状态调用，这是一个非常值得分享的后端设计实践。下面，我将为您精心撰写这篇技术博客，全面展示这个重构过程的设计思想和实现细节。

---

后端接口的“一鱼两吃”：如何优雅复用后台 API 适配小程序？🐟

嘿，各位后端开发者！👋 在我们的日常开发中，经常会遇到这样的场景：一个功能，既要在后台管理系统（Web端）上使用，也要在小程序或 App 端上使用。

最直接（也最“笨”）的方法是什么？复制粘贴！为小程序再写一套几乎一模一样的 Controller 和 Service。但这样做不仅违反了 DRY (Don’t Repeat Yourself, 不要重复自己) 原则，还会带来双倍的维护成本。

今天，我们就以一个“分页查询品牌下的产品列表”接口为例，分享一个非常实用的后端设计技巧：如何通过优雅的重构，让同一个 Service 方法，既能服务于后台的 Session 认证，又能适配小程序端的无状态 AppID 授权。

🎯 核心思想与成果对比

我们的目标是，用最小的改动，实现最大的复用。

对比项	重构前 (Separate Methods)	重构后 (Unified Method)
Service 层	两个类似的方法： listForAdmin(sessionAdminId, ...) listForWx(appId, ...)	一个通用方法： listProductsByBrandId(adminId, ...) ✅
Controller 层	各自调用不同的 Service 方法	各自调用同一个 Service 方法
代码冗余	较高，业务逻辑重复	极低，核心逻辑只在一处
维护成本	高，修改逻辑需要同步改两处	低，只需维护一个核心方法
设计模式	职责不清，Service 关心认证来源	职责清晰，Service 只关心业务，Controller 负责认证

🤔 重构之旅：从分离到统一

我们的重构之旅，本质上是一个 “责任上移” 的过程。即，将“如何获取 adminId”这个与认证相关的责任，从 Service 层完全移交给 Controller 层。

下面是这个决策流程的图示：

⚙️ 两种请求，同一处理流程

让我们通过一个时序图 (Sequence Diagram) 来看看，当后台和小程序的请求分别到来时，系统内部是如何以一种统一的方式处理的。

🔄 Service 层的状态：从“关心来源”到“专注业务”

我们可以把 Service 方法的状态看作一种演进。

🏛️ 类图：职责的重新划分

重构后，Controller 和 Service 的职责更加清晰，符合单一职责原则。

🔗 实体关系图：配置与授权

X-App-ID 授权模式的核心在于配置。下面是配置、管理员和品牌之间的实体关系图 (Entity Relationship Diagram, ERD)。

ERD (Entity Relationship Diagram, ERD)

🧠 思维导图总结

最后，让我们用一个思维导图来总结这次优雅重构的全过程。

通过这次重构，我们不仅让代码变得更整洁、更健壮，更重要的是，我们实践了一种优秀的后端架构思想。希望这个案例能给你在未来的项目开发中带来启发！Happy coding! 🚀