包含 api 开发原则、代码风格、mapper 扩展等。

api 开发总则

遵循单一职责原则，一个类只做一件（类）事。
数据库表与业务类是 1:N 的关系。
简单业务表建议只有一个业务类，复杂业务表，建议有多个业务类。

扩展阅读：面各对象设计的七大原则：

面向对象设计的七大原则

单一职责原则(Single Responsibility Principle, SRP)
开闭原则(Open-Closed Principle, OCP)
里氏代换原则(Liskov Substitution Principle, LSP)
依赖倒转原则(Dependence Inversion Principle, DIP)
接口隔离原则(Interface Segregation Principle, ISP)
合成复用原则(Composite Reuse Principle, CRP)
迪米特法则(Law of Demeter, LoD)

修改代码规范

不要影响以前代码的行为，不小心会带来新 bug。
随着新需求的引进，以前的代码可能已经不适用，要适当的重构。
不确定的，要及时与项目负责人沟通。
涉及到公共模板的修改，一般需要与项目负责人沟通之后才能修改，至少要让项目负责人知晓这件事。

代码风格，最基本的原则

与现在代码保持一致。
见名知义。
代码自解释。
对于不符合代码规约的，要在适当的时机重构。
为了代码的可读性和可维护性，牺牲实现功能的速度、牺牲运行性能也是有必要的，如果项目上线在即，可优先满足项目进度，但一定要及时重构。

悟出的命名规则

biz.dal.service 下的类，一定是表名（首字母大写）+ DalService
biz.dal.mapper.extend 下的类，一定是表名（首字母大写）+ MapperExt
biz\dal\mapper\xml\extend 下的 xml 文件名，一定跟 biz.dal.mapper.extend 下对应的 mapper 命名保持一致。
biz.service 下的类，一定是表名（首字母大写） + Service
biz.model.view 下的类，一定是以 View 结尾，前面部分根据业务来命名，以见名知义为准。
其余类似。

枚举定义注意事项

项目习惯定义，枚举包含 index 和 name 两个属性。

index 是不能重复的。
index 一般的步进值为10，这样，方便在需要的时候往中间插入新枚举。
name 一般为中文，可以表述枚举项的含义和作用。
枚举的 index 由前往后递增。

字段与枚举

带 flag 的字段，枚举用 YesOrNoEnum

/**
 * 成功 Or 失败
 */
public enum YesOrNoEnum {
    no(0, "否"),
    yes(1, "是");

    private int index;
    private String name;

    YesOrNoEnum(int index, String name) {
        this.index = index;
        this.name = name;
    }

    public int getIndex() {
        return index;
    }

    public void setIndex(int index) {
        this.index = index;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public static YesOrNoEnum getEnumByIndex(int index) {
        for (YesOrNoEnum result : YesOrNoEnum.values()) {
            if (index == result.index) {
                return result;
            }
        }

        return null;
    }

    public static YesOrNoEnum getEnumByName(String name) {
        for (YesOrNoEnum result : YesOrNoEnum.values()) {
            if (result.getName().equals(name)) {
                return result;
            }
        }

        return null;
    }

    public static String getNameByIndex(int index) {
        YesOrNoEnum enumItem = YesOrNoEnum.getEnumByIndex(index);

        if (enumItem != null) {
            return enumItem.getName();
        }

        return "";
    }
}

mapper 扩展

MGG 项目在 github 上的地址，有详细说明。
详细说明在本博客有副本：MyBatis Generator（MBG），写扩展类，以适应 MySQL 大小写敏感配置的各种情况、适应分表时动态替换表名

用 MBG 生成的代码对应目录下的文件，禁止修改，因为 MBG 更新之后，会把修改的代码覆盖掉。
如何添加自定义的扩展 mapper 方法？参见下面两个目录下的文件，一个为 mapper 扩展，一个为对应的 xml 文件。
- biz.dal\src\main\java\biz\dal\mapper\extend
- biz.dal\src\main\java\biz\dal\mapper\xml\extend
需要注意 MBG 版本，有针对 5.x 和的 8.x的。

MyBatis sql 脚本

sql 脚本里用到的表名，一定要用键盘横排【1 和！】键盘左边键的“单引号”引起来，用的是【`】，而不是平常用的真正的单引号【’】。
目的：分表用。

表结构修改流程

修改 PowerDesigner 文档，同时将修改同步至目录 C:\workspace\source\doc\sqlScripts 下对应的文件。
sql 脚本提交之后，通过执行修改后的表脚本，将修改同步至数据库。
用 MBG 工具重新生成 mapper 相关文件，提交更新。
提交更新时，在备注里写上需要执行的表脚本。
在项目管理工具对应的任务或者 bug 修改状态为【完成】时，直接提供需要执行的脚本，或者指定需要执行的文件。

一定要注意，PowerDesigner 与 C:\workspace\source\doc\sqlScripts 下对应的脚本文件，还有数据库，三者一定是一致的。

针对某字段的枚举命名规范

总则：见名知义、类命名规范。
如果字段名已经能够做到见名知义，则字段名首字母大写之后，直接在其后添加 Enum。
如果字段名在多张表出现（当然，要尽量避免这种情况，可以适当添加前缀来避免），或者字段名不具备见名知义的特点，则可以是：表名+字段名 + enum，如果表名太长，可以酌情适当修改。

js 代码提交

如果有影响页面的 js 代码提交，需要在 html 文件引用的地方，修改 v 的值，最好修改成当前时间，如：

<link rel="stylesheet" type="text/css" href="/static/wx/css/style.css" th:href="@{/wx/css/style.css} + '?v=201803011459'"/>
<script src="/static/public/js/apg.common.js" th:src="@{/public/js/apg.common.js} + '?v=201803030932'"></script>
<script type="text/javascript" src="/static/wx/js/cashDesk.js" th:src="@{/wx/js/cashDesk.js} + '?v=201803011459'"></script>
<script type="text/javascript" src="/static/wx/js/wxPay.js" th:src="@{/wx/js/wxPay.js} + '?v=201803011459'"></script>

本条规范适用于非react项目

新加配置项

放 newly 后面。目的：部署的时候，将 newly 后面的全部添加到线上，然后再将 newly 移至最后。

# newly

java 开发，适用于团队的代码规范及某些约定

2018-05-22
java
team
代码规约