碰到不遵守开发规范的后端程序员真的让人很恼火

让我们一起走向未来

🎓作者简介：全栈领域优质创作者

🌐个人主页：百锦再@新空间代码工作室

📞工作室：新空间代码工作室（提供各种软件服务）

💌个人邮箱：[15045666310@163.com]

📱个人微信：15045666310

🌐网站：https://meihua150.cn/

💡座右铭：坚持自己的坚持，不要迷失自己！要快乐

目录

在现代软件开发中，前端与后端的合作无疑是最为紧密的。无论是移动端应用、Web应用，还是企业级平台，前端和后端的接口对接都是构建系统的核心之一。作为前端人员，我们日常与后端对接接口时，最关注的就是接口的规范性、稳定性和易用性。然而，时常会遇到一些后端开发人员忽视或不遵循接口开发的基本规范，造成前端与后端之间的沟通障碍，不仅浪费时间和精力，还可能影响整个项目的进度与质量。更糟糕的是，长时间在这样的开发环境中工作，甚至可能让程序员的耐心与积极性遭遇严重考验。

一、接口设计不规范的常见问题

在前后端分离的开发模式下，接口是前端与后端之间的桥梁。如果后端在接口设计中不遵守规范，那么不仅前端的开发工作会变得困难重重，整个项目的协作效率也会大打折扣。下面列举了在实际开发中常见的几个“不遵守规范”的后端接口问题。

1. 接口命名不规范

接口命名是开发中最基础的部分，一个规范、简洁的接口命名能够让开发者快速理解接口的功能，而不规范的命名往往导致理解困难。我们来看看一些常见的接口命名问题：

• 命名不清晰或过于模糊

  举个例子，后端有一个查询用户信息的接口，结果接口命名为 getData 或 fetchInfo ，这样的命名让人摸不着头脑。我们无法清楚地知道这个接口到底是查询哪个数据，或者它的返回值包含哪些信息。一个清晰的接口命名应该表达出具体的行为和操作对象。例如 getUserInfo 或 fetchUserDetails 等。

  // 不规范的命名
  GET /api/getData
  // 规范的命名
  GET /api/user/{userId}

• 单一接口承担多种功能

  另一个常见的问题是，一个接口承担了多个功能的实现，导致接口命名混乱。例如 getUserInfoAndUpdateAddress 这样的命名，它包含了查询用户信息和更新地址两个功能，这种接口不仅命名混乱，功能也不单一，应该拆分成两个接口：

  // 不规范的命名
  GET /api/getUserInfoAndUpdateAddress
  // 规范的命名
  GET /api/user/{userId}
  PUT /api/user/{userId}/address

2. 接口返回的数据格式不规范

接口返回的数据结构直接影响到前端的开发效率。如果后端返回的数据格式不规范，前端需要花费大量时间来解析和适配这些数据，从而降低开发效率。以下是常见的几个问题：

• 缺乏统一的响应格式

  许多后端在接口返回时，没有统一的规范，导致每个接口的返回数据结构都不相同。例如，有的接口返回一个纯粹的对象，有的接口返回一个嵌套对象，而有的接口返回一个数组。在这种情况下，前端需要根据每个接口的实际情况来判断如何处理数据，这不仅增加了开发的复杂度，也容易导致代码混乱。

  // 不规范的返回格式
  GET /api/user/{userId}
  Response 1: { userId: 1, name: 'Tom' }
  GET /api/posts
  Response 2: { posts: [{ id: 1, title: 'Post Title' }] }

规范的做法是，所有接口的返回应该遵循相同的格式，例如 { status, message, data } ，即使返回的是不同的类型，前端也能统一进行处理：

// 规范的返回格式
GET /api/user/{userId}
Response: { status: 200, message: 'Success', data: { userId: 1, name: 'Tom' } }

GET /api/posts
Response: { status: 200, message: 'Success', data: { posts: [{ id: 1, title: 'Post Title' }] } }

• 返回的错误信息不明确

  错误信息的规范性同样非常重要，模糊或者不明确的错误信息会让前端很难处理错误情况。例如，后端返回一个 500 Internal Server Error ，但是并没有给出具体的错误原因。对于前端开发来说，错误信息越详细越好，能够帮助快速定位问题。

  // 不规范的错误返回
  {
    "error": "Internal Server Error"
  }
  
  // 规范的错误返回
  {
    "status": 500,
    "message": "Database connection failed",
    "error": "ConnectionTimeoutError"
  }

3. 接口参数不规范

• 参数命名不一致

  后端接口的参数命名应该尽量统一和标准化。不同的接口，如果参数命名不一致，可能导致前端需要多次去调整代码。例如，有的接口使用 user_id ，有的接口使用 userId ，这就增加了前端的开发难度。如果开发团队有一致的规范，前端和后端都能在调用时按照一致的命名方式来使用参数。

  // 不规范的参数命名
  GET /api/user?userId=1
  GET /api/user/address?user_id=1
  
  // 规范的参数命名
  GET /api/user?userId=1
  GET /api/user/address?userId=1

• 参数类型不一致

  参数类型不一致也是一个常见问题。例如，在请求体中传递数字类型参数时，后端却期望是字符串类型。或者在查询参数中传递日期格式时，前端传递的是不同的格式，导致后端解析失败，增加了前端的调试成本。

  // 不规范的参数类型
  GET /api/user?age="25"
  POST /api/user/update { "birthDate": "25-12-2021" }
  
  // 规范的参数类型
  GET /api/user?age=25
  POST /api/user/update { "birthDate": "2021-12-25" }

4. 接口文档不完善或缺失

没有规范的接口文档，前端在接入接口时非常容易遇到困扰。如果后端没有提供详细的接口文档，前端开发者就必须要通过请求后端来确认每个接口的具体功能和参数，极大地增加了沟通成本。例如，有的后端接口没有描述清楚返回数据的结构，前端就无法预见如何处理这些数据，导致前端代码经常修改或者接口对接频繁出错。

• 接口文档缺失

  如果没有接口文档，前端只能通过后端提供的代码或者口头描述来理解接口，而这往往不是很清晰，甚至可能导致严重的误解。

  规范的做法是，后端每次提交接口时，都应该提供详细的接口文档，并确保文档与代码的一致性。接口文档不仅要包含接口的请求方式、参数、返回值、错误代码等，还要给出实际的示例，以便前端开发人员快速理解。

  // 规范的接口文档示例
  Endpoint: GET /api/user/{userId}
  Parameters:
    userId: integer (required) - The ID of the user to be retrieved
  Response:
    200 OK:
      {
        "status": 200,
        "message": "Success",
        "data": {
          "userId": 1,
          "name": "Tom"
        }
      }
    404 Not Found:
      {
        "status": 404,
        "message": "User not found"
      }

5. 没有进行合理的接口版本管理

当项目开始进行版本升级时，接口的版本管理就显得尤为重要。没有良好版本控制的接口可能在无预警的情况下发生变动，导致前端系统无法正常运行。接口版本化应该是后端开发的常规操作，通过在接口的URL或者请求头中明确版本号，确保前端与后端的兼容性。

// 不规范的接口版本管理
GET /api/user

// 规范的接口版本管理
GET /api/v1/user

二、如何避免这些问题，推动团队的开发规范化

作为前端开发人员，我们并不能直接改变后端的开发习惯，但可以通过沟通和协作推动开发团队遵循更规范的开发流程和接口设计方法。以下是一些改进和推动的建议：

1. 建立统一的接口设计规范

团队可以制定统一的接口设计规范，包括命名规范、数据格式规范、错误处理规范等。这样，前端和后端都能按照统一的规则来进行开发和对接，减少沟通和开发中的不确定性。

2. 编写清晰的接口文档

后端应该提供详细的接口文档，列出每个接口的功能、参数、返回值、错误信息等。文档可以采用Swagger等工具生成，前端可以快速查阅，并进行接口调试。

3. 定期进行前后端对接和沟通

前端和后端应该定期进行接口对接会议，及时沟通接口的变更，解决出现的问题。通过有效的沟通，减少接口开发中的不规范行为，确保前后端的协作顺畅。

4. 采用自动化测试

通过自动化测试工具进行接口测试，可以帮助团队提前发现接口设计中的问题。使用Postman等工具进行接口测试，自动化脚本可以确保接口返回数据的正确性，减少人为错误。

5. 加强代码审查和接口审核

团队内部应该进行代码审查，确保接口的设计和实现符合规范。在项目开发的各个阶段，进行接口审核和测试，及时发现并修复问题，避免开发过程中出现不规范的情况。

结语

前后端接口是现代Web开发中最基础也最重要的部分。作为前端人员，我们往往希望后端能够遵循一定的开发规范，这样才能保证接口的高效、稳定和易用性。希望通过本文的分析，能够帮助开发者们认识到接口设计中的一些常见问题，并推动团队在接口开发中建立更好的规范。最终，前后端的高效协作将为整个开发团队带来更高的工作效率和更好的项目质量。