IIDP开发规范.pdf

前言

《IIDP开发规范》是赛意工业软件及物联子公司技术平台研发团队，基于IIDP低代码平台设计、开发和测试过程中，汇集团队内部和外部交付团队集体的智慧结晶和开发经验总结，经历了从零开始自研IIDP低代码平台，多次大规模一线实战的检验及不断的完善，系统化地整理成册，回馈给开发者的一份开发规范。现代软件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终交付质量。企业数字化转型，需要部署大量企业级应用，随着业务的发展，需求无法得到及时响应，大大增加了数字化转型的成本，这也是我们开发IIDP的初衷，极大地给开发者带来了很多开发方面的便利和快捷，同时为了提高开发者编码的质量和可靠性，我们也约定了很多规范，比如：对象命名的混乱带来代码的不好维护；模型设计的不规范带来从一开始就导致设计上的混乱给；数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险；工程结构混乱导致后续维护艰难；没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以IIDP开发者为中心视角，划分为编程规范、测试规范、授权管理规范、版本管理规范、工程结构规范、部署规范等几个维度，再根据内容特征，细分成若干二级子目录。根据约束力强弱及故障敏感性，规约依次分为【强制】、【推荐】、【参考】三大类。对于规约条目的延伸信息中，“说明”对内容做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实的错误案例。

现代软件架构都需要协同开发完成，高效协作即降低协同成本，提升沟通效率，所谓无规矩不成方圆，无规范不能协作。众所周知，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全。试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率。代码的字里行间流淌的是软件生命中的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升质量意识。

希望IIDP开发者通过阅读本手册，能够充分利用IIDP平台进行开发，避免常见的错误和陷阱，写出高质量的代码，提高开发效率。让我们一起码出高效、码出质量的软件系统。

编程规范

API调用规范

1.【强制】前端调用后端api必须指定app（分布式部署场景下）
说明：平台交付最小单元就是app，接口调用时必须指定app的名字
正例：传参中包含app，model，service，其中app是model所在的app
反例：传参中只有model和service,未提供app或app错误

命名规范

1.【强制】 app命名规范。应用名称必须唯一，必须在app.json中定义，使用业务含义的应 用名称作为前缀。（长度，允许包含哪些字符，开头。保留关键字，平台预留）

说明：在IIDP平台中，app是名称唯一标识，确保应用名称的唯一性，便于识别和管理。
正例：iot_net / iot_base / smi_base / smi_redis / snest_tenant / snest_log / snest_base 等大的项目名称作为前缀，具体的业务场景作为后缀名称，具有业务含义，也能唯一区分。
反例：net / base / log 等模糊或不具有业务含义的名称很容易重名，且不知道是具体哪个项目的名称。

2.【强制】模型命名规范。模型名称必须唯一，并在注解中定义。推荐使用业务含义的模型名称作为前缀。
说明：在IIDP平台中，模型名称是名称唯一标识，对应着数据库中的表名称，使用下划线拼接，控制字符串长度，确保应用名称的唯一性，便于识别和管理。
正例：tenant_action_rule / tenant_rbac_organization 等大的项目名称作为前缀，具体的业务场景作为后缀名称。 反例：net_model / base_model / logModel 等，不需要加model后缀，不需要采用驼峰拼接，且不知道是具体哪个项目的名称。

常量定义

1.【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

正例：通过枚举值定义模型类型

public static enum ModelType {
    Default,
    Define,
    Buss,
    Memory,
    Data,
    Cache,
    Config,
    Tree,
    Template,
    View;

    private ModelType() {}
}

反例：模型名称用字符串，调用方法也是字符串。导致其他地方使用这个模型名称时，需要重新再写一遍字符串，如果修改了一处，另外一处不会自动同步修改。

this.getMeta().get("rbac_tenant").callSuper(Tenant.class, "create", valuesList);

模型规范

1.【参考】基于元模型驱动的平台核心思想：一切皆模型、模型可扩展可继承。
说明：关于平台的几点说明：
1、每个元模型都有唯一身份证；
2、平台的模型不仅提供属性、服务等能力，模型之间还可以方便进行继承、扩展；
3、模型还分了业务模型（缓存与db的存储与访问能力）、数据模型（内存存储和访问能力）、树状模型（行级存储与访问能力）等；
4、业务模型根据是否抽象来确定是否需要建立表；

在线IDE使用规范

1.【参考】基于元模型驱动的平台核心思想：一切皆模型、模型可扩展可继承。

SDK使用规范

1.熟悉SDK文档和功能：
在开始使用SDK之前，仔细阅读官方文档，了解SDK提供的功能和用法。 理解SDK的设计理念和工作原理，以便正确地使用和集成SDK。

2.遵循SDK的最佳实践：
官方文档已提供一些最佳实践和推荐的使用方式，尽量遵循这些指南。 遵循SDK的设计模式和约定，以便与其他开发者更好地协作。

3.使用适当的错误处理机制：
当使用SDK的方法或者函数时，要注意捕获和处理可能发生的异常。 根据SDK提供的错误码或者异常类型，进行适当的错误处理，例如记录日志、返回错误信息等。

4.避免滥用SDK：
只使用SDK提供的必要功能，避免滥用SDK的高级功能，以免增加复杂性和性能开销。 不要过度依赖SDK，尽量保持代码的灵活性和可扩展性。

5.使用SDK提供的扩展点： 如果SDK提供了扩展点或者插件机制，可以使用这些机制来自定义功能或者扩展SDK的行为。

6.更新和升级SDK：
定期检查SDK的新版本和更新，了解新功能、修复的问题和性能改进。 在合适的时机，考虑升级到新版本的SDK，以获得更好的功能和性能。

7.与SDK开发者保持互动：
如果SDK有相关的群聊或者社区，可以积极参与其中，与其他开发者交流经验和解决问题。提交反馈和建议，帮助SDK的改进和发展。（外网可访问的在线文档，反馈和建议的途径）
8.IIDP SDK使用规范
api调用 filter crud
与前端页面交互
总之，SDK使用规范的核心是熟悉SDK的功能和用法，并遵循官方文档中的建议和最佳实践。合理地使用SDK，并与其他团队成员保持一致的使用方式，可以提高代码的可读性、可维护性和可扩展性。

日志规范

1.【强制】IIDP引擎日志规范。
说明：IIDP引擎对通用的日志接口进行封装，规范日志打印格式，自动追加引擎相关日志信息，比如自动最佳model service等信息，自动可知道访问的是哪个model哪个service，基于这种结构化的日志，便于后续的日志分析。

2.【强制】在日志输出中包含有用的上下文信息。 说明：日志应该包含有助于定位问题的上下文信息，例如时间戳、线程ID、请求ID、关键参数值等。

后端视图规范

1.【强制】同一个后端视图内按钮的 auth 要求唯一 说明：后端视图，例如 grid 视图，buttons 和 tabr 可以声明多个按钮。如果是调用自定义服务的按钮，auth 必须唯一，并且不能与默认权限 read、update、create、delete 相同。否则会导致不能单独对某个按钮进行授权。

反例

"buttons": [
    {
        "action": "edit",
        "auth": "update",
        "name": "编辑"
    },
    {
        "name": "发布",
        "auth": "update",
        "service": "updateApp",
        "model": "meta_app"
    },
    {
        "name": "生成视图",
        "auth": "update",
        "service": "buildDefaultViews",
        "model": "meta_model"
    }
]

正例

"buttons": [
    {
        "action": "edit",
        "auth": "update",
        "name": "编辑"
    },
    {
        "name": "发布",
        "auth": "updateApp",
        "service": "updateApp",
        "model": "meta_app"
    },
    {
        "name": "生成视图",
        "auth": "buildDefaultViews",
        "service": "buildDefaultViews",
        "model": "meta_model"
    }
]

测试规范

单元测试

1.【强制】编写独立、可重复执行的单元测试。 说明：单元测试应该是独立的、不依赖外部资源的测试，可以在任何环境下重复执行。确保每个单元测试之间相互独立，不会相互影响，提高测试的可靠性和可维护性。

2.【强制】使用适当的测试框架和断言库。 说明：选择适合项目的测试框架（如JUnit、TestNG等）和断言库（如AssertJ、Hamcrest等），以便编写清晰、简洁的测试代码，并提供丰富的断言方法来验证测试结果的正确性。

3.【强制】 测试覆盖率达到预定目标。 说明：测试覆盖率是衡量测试代码覆盖业务代码的程度的指标。根据项目的需求和复杂度，设定合理的测试覆盖率目标，并确保单元测试覆盖率达到或超过这个目标。

4.【强制】 每个单元测试应该只测试一个功能点或场景。 说明：每个单元测试应该聚焦于测试一个特定的功能点或场景，避免将多个功能点或场景混合在一个测试中。这样可以提高测试的可读性和可维护性，并能更准确地定位问题。

5.【强制】 使用合适的测试数据进行测试。 说明：在编写单元测试时，应该使用合适的测试数据来覆盖不同的情况和边界条件，以验证代码在各种情况下的正确性。包括正常情况、边界情况、异常情况等。

6.【强制】验证预期的行为和结果。 说明：每个单元测试应该明确验证预期的行为和结果，通过断言来判断测试是否通过。确保测试代码能够准确地验证被测试代码的行为和结果。

功能测试

1.【强制】验证系统的用户界面（UI）功能。 说明：功能测试应该验证系统的用户界面功能是否符合预期，包括页面布局、交互操作、表单验证等。通过功能测试可以确保用户界面的可用性和易用性。

集成测试

性能测试

【推荐】性能测试是评估系统在不同负载条件下的性能表现的过程。为了确保性能测试的准确性和可重复性，需要遵循一套规范和最佳实践。 以下是性能测试规范的一些要点：

(1)目标定义：明确性能测试的目标和需求。确定要测试的系统组件、功能或场景，以及期望的性能指标，如响应时间、吞吐量、并发用户数等。
(2)测试环境：建立逼近真实生产环境的测试环境。包括硬件、网络、操作系统、数据库等方面的配置和设置。确保测试环境与生产环境的相似性，以便更准确地模拟实际情况。

(3)测试数据：使用真实、多样化的测试数据进行性能测试。测试数据应该涵盖典型场景和边界情况，并具有一定的数据量和变化。

(4)测试脚本和工具：编写清晰、可重复执行的性能测试脚本。选择适当的性能测试工具，如JMeter、LoadRunner等，用于执行和监控性能测试。
(5)负载模拟：根据实际使用情况和预期负载，设计和模拟不同负载条件下的测试场景。包括正常负载、峰值负载、压力测试等。确保测试覆盖了系统的不同使用情况和负载情况。

(6)测试监控和度量：监控系统在测试过程中的各项性能指标，如响应时间、CPU利用率、内存使用等。使用合适的监控工具和指标，以便及时发现性能瓶颈和问题。

(7)结果分析和报告：对性能测试结果进行分析和总结。识别性能瓶颈、性能优化的潜力和建议等。生成详尽的测试报告，包括测试配置、执行过程、结果数据和结论。

(8)迭代和持续测试：性能测试应该是一个迭代的过程，随着系统的演化和变化，不断进行性能测试和优化。同时，建立持续性能测试的机制，确保系统在每次发布和部署后的性能稳定性。

通过遵循性能测试规范，可以提高性能测试的准确性、可重复性和可靠性。这有助于发现和解决系统的性能问题，提升系统的性能和可扩展性，提供更好的用户体验。

自动化测试

元模型自动化测试 自动化测试工具

回归测试

1.【强制】所有代码必须进行单元测试，确保功能的正确性和稳定性。
说明：单元测试是保证代码质量的重要手段，通过编写针对各个模块和函数的测试用例，可以验证代码的正确性和稳定性。所有代码的提交前必须通过相应的单元测试。

授权管理规范

平台授权

1.【强制】dev开发环境不需要授权，但Dev无法使用应用市场。

2.【强制】在启动iidp平台之前，必须进行授权操作。
说明：为了确保iidp平台的安全性和合规性，必须在启动之前进行授权操作。授权可以包括但不限于身份验证、访问权限控制等措施，以确保只有经过授权的用户可以访问和使用iidp平台。具体的授权方式可以根据实际情况进行选择和实施。

多租户

1.【强制】多租户授权
说明：每一个租户的创建都必须进行授权，包括租户能够使用的应用和数量，防止大规模使用多租户功能。

2.【强制】行列权限控制规范
说明：平台基于元模型进行行、列权限控制，在模型处理逻辑一致的情况下，可以通过权限控制实现千人千面效果。

版本管理规范

GIT使用规范

1.【建议】不建议使用rebase。
说明：虽然rebase能够使得提交的commit线很整洁，但这并不是实际的提交记录的真正反应，而且由于rebase会重新生成commit id，可能会导致很多冲突的情况。

2.【强制】使用版本管理工具Git进行代码版本管理。 说明：Git是一种分布式版本控制系统，可以有效地管理代码的版本和变更历史。通过使用Git，可以轻松地进行代码的协作开发、版本回退、分支管理等操作，提高团队协作效率和代码质量。

3.【强制】使用合适的分支策略进行代码开发和管理。 说明：合适的分支策略可以有效地组织代码的开发和管理流程，常见的分支策略包括主分支（master/main）、开发分支（develop）、特性分支（feature）、发布分支（release）、修复分支（hotfix）等。根据具体项目和团队的需求，选择合适的分支策略进行代码管理。

4.【强制】提交代码前进行代码审查。
说明：代码审查是保证代码质量和一致性的重要环节。通过代码审查，可以发现潜在的问题和错误，提高代码的可读性和可维护性。在提交代码之前，应邀请其他团队成员进行代码审查，并根据审查结果进行相应的修改和优化。

5.【强制】使用有意义的提交消息。 说明：提交消息是对代码变更的简要描述，应该清晰、有意义且符合规范。提交消息应该包含变更的目的、内容和影响等信息，方便其他团队成员理解和追踪代码变更历史。 正例： ``` feat: 添加用户注册功能

 添加了用户注册功能，包括表单验证、数据存储和页面跳转等功能。
 ```
 反例：
 ```
 fix: 修复bug
 
 修复了一个bug。
 ```

6.【强制】遵循代码合并流程，确保代码的一致性和稳定性。 说明：代码合并是将不同分支上的代码合并到一起的过程，应该遵循合适的合并流程，包括解决冲突、测试合并后的代码等步骤，确保合并后的代码一致性和稳定性。

7.【强制】使用标签管理发布版本。

说明：标签是对特定版本的代码进行命名和标记，方便追踪和发布。在每次发布稳定版本时，应该创建相应的标签，并注明版本号和发布日期等信息。

8.【建议】使用Git Hooks进行代码质量检查。 说明：Git Hooks是Git提供的钩子机制，可以在特定的Git操作触发相应的脚本。通过使用Git Hooks，可以在代码提交、合并等操作前进行代码质量检查，例如代码格式化、静态代码分析等，提高代码的质量和一致性。

9.【建议】使用Git Flow等工具辅助分支管理。 说明：Git Flow是一种流行的Git分支管理工具，可以简化分支管理流程，提供命令行工具和图形界面工具来支持分支的创建、合并、发布等操作。使用Git Flow等工具可以提高分支管理的效率和可靠性。

10.【建议】定期进行代码仓库的维护和清理。 说明：定期进行代码仓库的维护和清理可以减少仓库的冗余和混乱，提高代码仓库的性能和可用性。包括删除不再需要的分支、清理过期的标签、整理和优化仓库结构等操作。

11.【建议】使用Git相关的工具和服务进行代码托管和协作开发。 说明：Git相关的工具和服务提供了丰富的功能和便捷的操作，可以方便地进行代码托管、协作开发、问题追踪等工作。常见的Git工具和服务包括GitHub、GitLab、Bitbucket等，根据团队的需求选择合适的工具和服务进行使用。

以上是使用Git的一些常见规范，包括分支管理、代码审查、提交消息、合并流程等方面根据具体项目和团队的需求，可以进行相应的调整和补充

CICD规范

1.【强制】 使用CI/CD工具进行自动化的代码构建、测试和部署。 说明：CI/CD（持续集成/持续部署）是一种软件开发实践，通过自动化的流程来构建、测试和部署代码，以提高开发效率和软件质量。选择合适的CI/CD工具（如Jenkins、GitLab CI、Travis CI等）来配置和管理CI/CD流程，确保代码的自动化构建、测试和部署。

2.【强制】 将CI/CD配置文件纳入版本控制。 说明：CI/CD配置文件是定义CI/CD流程的文件，应该将其纳入版本控制，与代码一起进行管理。这样可以确保CI/CD配置与代码版本的一致性，方便团队成员查看和修改CI/CD配置。

3.【强制】 在CI/CD流程中包含代码编译、单元测试和静态代码分析等步骤。 说明：CI/CD流程应该包含代码的编译、单元测试和静态代码分析等步骤，以确保代码的质量和稳定性。在编译阶段，将源代码编译成可执行的程序或库；在单元测试阶段，运行针对代码的单元测试，验证代码的正确性；在静态代码分析阶段，使用工具对代码进行静态分析，检查潜在的问题和代码质量。

4.【强制】 使用环境变量管理敏感信息。 说明：敏感信息（如数据库密码、API密钥等）应该通过环境变量进行管理，而不应直接写入代码或配置文件中。在CI/CD流程中，使用环境变量来获取敏感信息，并确保在不同环境中使用不同的敏感信息。

5.【强制】 在CI/CD流程中进行集成测试和部署到测试环境。 说明：在CI/CD流程的后续阶段，应该进行集成测试和部署到测试环境。集成测试是对不同模块或服务的集成进行测试，验证系统的整体功能和兼容性；部署到测试环境是将代码部署到与生产环境相似的测试环境中，以进行更全面的测试和验证。

6.【强制】 使用持续集成服务器进行自动化构建和测试。 说明：持续集成服务器是用于执行CI/CD流程的服务器，可以自动触发代码构建、测试和部署。通过配置持续集成服务器，可以实现代码的自动化构建和测试，提高开发效率和代码质量。

7.【强制】 使用容器化技术进行部署。 说明：容器化技术（如Docker）可以将应用程序及其依赖项打包成独立的容器，提供了一致的运行环境，方便部署和扩展。在CI/CD流程中，可以使用容器化技术将应用程序打包成镜像，并在部署阶段使用这些镜像进行快速部署和回滚。

8.【建议】 使用自动化测试工具进行端到端测试。 说明：自动化测试工具可以模拟用户的行为，对整个应用程序进行端到端的测试，以验证系统的功能和性能。在CI/CD流程中，可以使用自动化测试工具进行端到端测试，提高测试的覆盖范围和准确性。

9.【建议】 使用日志和监控工具进行应用程序的监控和故障排查。 说明：日志和监控工具可以帮助监控应用程序的运行状态和性能指标，并及时发现和排查故障。在CI/CD流程中，可以配置日志和监控工具，以便在部署后及时获取应用程序的运行情况，并进行故障排查和优化。

10.【建议】 定期审查和优化CI/CD流程。 说明：CI/CD流程是一个持续演进的过程，应该定期审查和优化流程，以适应项目的需求和变化。通过审查和优化CI/CD流程，可以提高开发效率和代码质量，减少部署和发布的风险

发版规范

APP版本规范

1.App的名称，版本，描述，产品线（分类，业务领域，不好约定，业务行为）
2.行业，领域，分类的方式体现

工程结构规范

APP设计规范

3.【推荐】app的拆分推荐考虑基于商业角度、复用性、职责、性能、部署场景等要素综合考虑后进行拆分，业务的变化是复杂的，要基于具体的业务场景来进行设计，这点非常非常重要，关系到后续的具体业务开发的方向。 说明：具体app的拆分规范主要包括以下几个方面： 1、对app进行分层 app层级越低则通用性越强，层级越高则有更多的通用app选择，可以拿来即用或通过扩展使用。随着app层级清晰且越来越多，可以逐步形成app货架： (1)L1:平台通用app 包括运维、权限、中间件集成、api集成、数据流处理等相关的app (2)L2:业务通用app 包括通知、告警、文件、字典、审批流、打印、主数据等业务通用app (3)L3:产品通用app 包括Iot、smi、qms等产品通用app (4)L4:行业通用app 包括电子套件、pcb、光伏等行业app (5)L5:定制app 包括各类企业定制的app

2、按商业模式划分app 哪些应用、模块、功能是打算独立销售的，可以将这些功能封装到独立app中。

3、按耦合程度划分app 可参考DDD，识别领域模型、聚合根等，将高内聚的模型封装在一个app。

4、识别并分离不变与变化app 将不变的或很少变化的模型封装在一个app，将变化频繁的模型、或扩展模型封装在另外的app。

5、识别高并发场景 将对性能要求非常苛刻的模型封装到独立app中。

4.【推荐】app调用关系规范 说明：appA方法或服务调用到另外一个appB的方法或服务，这是调用关系： (1)调用关系相关方app具备安装顺序无关性; (2)调用关系会影响到运行时的方法或服务调用，如指定appB的方法或服务找不到.

5.【推荐】app依赖关系规范 说明：appA与另外appB的属性之间具备ER关系，或模型之间具有继承、扩展关系，这是依赖关系，我们应梳理好依赖关系后再进行建模，以免导致循环依赖： (1)A继承/扩展了B的模型，必须要先装B，再安装A; (2)A与B的模型之间可能存在1:N、N:1、N:N三种ER关系，N:1与N:N支持单边关系，

6.【推荐】单边关系与双边关系使用规范 说明：可以独立安装，1:N不支持单边关系需要N方先安装，因此在使用1:N时需要尽 量避免循环依赖。平台支持N:1、N:N的单边关系，特别适用于跨App扩展ER关系的 场景，在保证不改动原App的情况下，扩展ER关系： 1、双边关系 模型双方建立ER关系，可以双向获取对端的数据 2、单边关系 模型A建立关联模型B的ER关系，B不需要配置与A的关系，适用于通过A获取B,但是不需要通过B获取A。如：业务模型关联码表，码表不需要关联业务模型。

7.【推荐】跨模型方法调用规范 说明：平台为了保证扩展能力，所有的模型、属性、服务等都是可以动态扩展的，因此 本质上每个元模型都是Map,而不是具体的Class： 1、不建议在平台中用new模型的方式创建对象 2、调用方法也应该采用统一的call方法 get set方法建议采用平台提供的模板（基于idea模版）

pom引入规范

1.【强制】禁止引入hutool包。 2.第三方的包，谨慎引入，防止app打包体积过大 3.pom编写规范

工程结构规范

代码目录结构，怎么安排，命名，约定大于配置 Model、app.json、views、service 必须在同一级目录 Views里面的文件内容字段命名和model里面的字段有关系。 字符串关联，编译插件来识别并提示。 运行阶段，提示字符串相关问题，可以考虑通过静态分析来进行处理。 由于引擎是一个jar包，在开发环境中，通过一个引擎jar包来加载正在开发的apps，对于调试非常不友好，建议通过新建一个server项目依赖引擎jar包，以及必要的配置（如端口配置）来启动引擎，加载正在开发的apps进行调试

公共错误码规范

【推荐】在开发和测试过程中，定义和使用一套统一的公共错误码规范可以提高代码的可读性、可维护性和可测试性。公共错误码规范定义了一系列标准错误码及其对应的错误信息，使得开发人员和测试人员能够快速理解和处理错误情况。 具体要求和建议如下： (1)错误码命名规范：定义一套统一的错误码命名规范，例如使用大写字母和下划线分隔的形式，例如：INVALID_PARAMETER。 (2)错误码分类：根据错误类型或模块进行分类，例如将参数相关的错误码放在一个范围内，将数据库相关的错误码放在另一个范围内。这样可以更好地组织和管理错误码。 (3)错误码取值范围：为每个错误码定义一个取值范围，以便后续的扩展和维护。例如，可以为参数相关的错误码分配范围为 1000-1999，数据库相关的错误码分配范围为 2000-2999。 (4)错误码文档化：为每个错误码提供清晰的错误信息和解释，以便开发人员和测试人员能够快速理解错误的含义和处理方式。这些信息可以在代码注释、文档或错误码定义文件中进行记录。 (5)错误码使用范围：明确错误码的使用范围，例如哪些模块或功能应该使用哪些错误码。这样可以避免错误码的混乱和重复使用。 (6)错误码的处理和返回：在代码中正确处理错误码，并根据错误码返回适当的错误信息给用户或调用方。错误信息应该清晰、准确地描述错误的原因，帮助用户或调用方理解和解决问题。 通过制定和遵守公共错误码规范，可以提高代码的可维护性和可测试性，减少错误处理的复杂性，并提供更好的用户体验。同时，还能够促进团队之间的协作和沟通，减少因错误处理不一致而引起的问题。

部署规范

前端部署

1.【强制】获取真实IP时，需要在Nginx配置中添加以下配置项：

反例：未添加上述配置项，导致后端服务器无法获取到真实IP地址。 根据上述新增规范，应在Nginx的配置文件中添加配置项proxy_set_header X-Real-IP remote_addr 和 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for，以确保能够获取到客户端的真实IP地址。

后端部署

1.【强制】部署模式，确定是单机版部署还是分布式模式部署。 说明：由配置文件中的engine.run.mode=SINGLE 配置项确定。 2.【推荐】用linux，不要用windows 说明：在开发和部署过程中，选择适合的服务器操作系统对于项目的稳定性和性能至关重要。Linux 作为一种开源操作系统，具有广泛的支持和强大的性能优势，尤其在服务器领域表现出色。相比之下，Windows 服务器在某些方面可能不如 Linux 服务器稳定和高效。 正例：使用 Linux 服务器可以获得更好的性能和稳定性。它提供了强大的命令行工具和灵活的配置选项，适用于各种服务器应用和开发环境。 反例：使用 Windows 服务器可能会面临一些限制和性能瓶颈。Windows 操作系统相对较重，可能需要更多的系统资源，并且在某些情况下可能不够稳定。 请注意，选择适合的服务器操作系统应根据具体项目需求和技术栈来决定。在某些特定情况下，使用 Windows 服务器可能是必要的，比如需要与 Microsoft 技术栈紧密集成的项目。然而，总体而言，推荐使用 Linux 服务器可以获得更好的性能和稳定性。

3.【强制】开发环境和部署环境要保持一致 说明：为了确保代码在不同环境中的一致性和可靠性，开发环境和部署环境应该尽可能保持一致。这包括操作系统、软件版本、配置文件等方面的一致性。 正例：在开发过程中，使用与目标部署环境相同的操作系统和软件版本进行开发和测试。确保开发团队和部署团队使用相同的工具链和依赖项，以减少环境差异可能带来的问题。 反例：在开发过程中使用不同于目标部署环境的操作系统或软件版本，导致在部署时出现兼容性问题或意外的行为差异。 通过保持开发环境和部署环境的一致性，可以最大程度地减少因环境差异而引起的问题。这样可以更好地预测和管理应用程序的行为，并提高部署过程的可靠性和效率。同时，也方便开发团队和运维团队之间的协作和沟通，减少因环境差异而导致的沟通和排查问题的成本。 需要注意的是，有时候在开发环境和部署环境之间可能存在一些差异，比如数据库的配置、外部服务的依赖等。在这种情况下，应该及时通知和协调相关团队，确保环境差异被妥善处理，并进行必要的测试和验证，以确保代码在部署环境中的正常运行