爱背单词不摆烂——代码规范

[爱背单词不摆烂]

这个作业属于哪个课程	2302软件工程
这个作业要求在哪里	团队作业——beta冲刺+事后诸葛亮
团队名称	爱背单词不摆烂
这个作业的目标	确认代码规范
置顶随笔链接	爱背单词不摆烂——Beta冲刺置顶集合随笔
其他参考文献	《构建之法》

---

目录

• 一、前端代码规范
• 参考文档：https://v2.cn.vuejs.org/v2/style-guide/index.html
• 二、后端代码规范
• 1 编程规约
• 1.1 方法参数类型必须一致，不要出现自动装箱拆箱操作
• 1.1.1 反例
• 1.1.2 正例
• 1.2 SimpleDateFormat是线程不安全的
• 1.2.1 反例
• 1.2.2 正例
• 1.3 使用equals方法应该注意空指针
• 1.3.1 反例
• 1.3.2 正例
• 2 异常日志
• 2.1 事务场景中如果异常被被捕获要注意回滚
• 2.1.1 反例
• 2.1.2 正例
• 2.2 不要在 finally 块中使用 return
• 2.2.1 反例
• 2.2.2 正例
• 2.3 应用中不可直接使用日志系统（Log4j、Logback）中的 API
• 2.4 所有日志文件至少保存15天
• 3 单元测试
• 3.1 好的单元测试必须遵守 AIR 原则
• 3.2 单元测试应该是全自动执行的，并且非交互式的
• 3.3 单元测试是可以重复执行的，不能受到外界环境的影响
• 4 安全规约
• 4.1 用户敏感数据禁止直接展示，必须对展示数据进行脱敏
• 4.2 用户请求传入的任何参数必须做有效性验证
• 5 MySQL 数据库
• 5.1 表明命名规范
• 5.2 表必备的几个字段
• 6 工程结构
• 6.1 线上应用不要依赖 SNAPSHOT 版本
• 6.2 注意POM坐标冲突
• 三、移动端代码规范
• 四、代码规范原文件

---

一、前端代码规范

参考文档：https://v2.cn.vuejs.org/v2/style-guide/index.html

• 常量命名：全部大写

  使用大写字母和下划线来组合命名，下划线用以分割单词

• 组件命名

  声明和使用都使用首字母大写命名

• 组件的 data 必须是一个函数。

  当在组件中使用 data property 的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。

• v-for 设置键值

  总是用 key 配合v-for。

  使用不一样的key值避免更新时出现错误

• 不同时在一个元素上使用v-for和v-if

• 分离组件

  当某块内容需要在多个页面时，抽离成组件。

• 自闭合组件

  在单文件组件、字符串模板和 JSX 中如果没有其他内容写出自闭合组件

• 指令缩写

​ 用:代替v-bind,@ 表示 v-on:

二、后端代码规范

1 编程规约

1.1 方法参数类型必须一致，不要出现自动装箱拆箱操作

1.1.1 反例

这种操作很容易产生难以排查的NPE异常

/**
  * 反例
  * 容易出现空指针异常，如果参数为null就会拆箱失败空指针错误
  * 排查的时候很难排查，因为直接看代码看起来不会出现空指针的。
  * @param value
  * @return
  */
public static int handel(Integer value) {
    return value;
}

1.1.2 正例

入参以及出参，和参数传递类型是一致的

public static Integer handel(Integer value) {
    return value;
}

1.2 SimpleDateFormat是线程不安全的

SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为 static， 必须加锁，或者使用 DateUtils 工具类

1.2.1 反例

使用这种方式在多线程的情况下会报错，或者出现数据不一致的情况

private static final SimpleDateFormat dateFormate = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");

1.2.2 正例

使用ThreadLocal的方式保证线程安全，或者使用DateTimeFormatter代替SimpleDateFormat

private static final ThreadLocal<SimpleDateFormat> threadLocal = new ThreadLocal<SimpleDateFormat>() {
    @Override
    protected SimpleDateFormat initialValue() {
        return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
    }
};

1.3 使用equals方法应该注意空指针

1.3.1 反例

如果object为null就会抛出NPE异常

object.equals("test");

1.3.2 正例

应该使用常量或者确定的值来进行判断equals

"test".equals(object);

或者使用Objects.equals

Objects.equals(object1,object2)

2 异常日志

2.1 事务场景中如果异常被被捕获要注意回滚

2.1.1 反例

@Service
@Transactional(rollbackFor = Exception.class)
public class UserServiceImpl implements UserService {
    @Override
    public void save(User user) {
        try{
        //some code
        //db operation
        }catche(Exception e){
            
        }
    }
}   

2.1.2 正例

@Service
@Transactional(rollbackFor = Exception.class)
public class UserServiceImpl implements UserService {
    @Override
    public void save(User user) {
        try{
        //some code
        //db operation
        }catche(Exception e){
            //捕获处理后需要再将异常抛出
            throw  e;
        }
    }
}   

2.2 不要在 finally 块中使用 return

try 块中的 return 语句执行成功后，并不马上返回，而是继续执行 finally 块中的语句，如果此处存 在 return 语句，则在此直接返回，无情丢弃掉 try 块中的返回点。

2.2.1 反例

这种情况下结果永远返回的都是true，fanally中不要做返回操作

public static boolean getValue(String text) {
    try {
        return text.equals("123");
    } finally {
        return true;
    }
}

2.2.2 正例

public static boolean getValue(String text) {
    return "123".equals(text);
}

2.3 应用中不可直接使用日志系统（Log4j、Logback）中的 API

在Java生态体系中，围绕着日志，有很多成熟的解决方案，关于日志输出，主要有两类工具。

    一类是日志框架，主要用来进行日志的输出的，比如输出到哪个文件，日志格式如何等，另外一类是日志门面，主要一套通用的API，用来屏蔽各个日志框架之间的差异的。

    所以，对于Java工程师来说，关于日志工具的使用，最佳实践就是在应用中使用如Log4j + SLF4J 这样的组合来进行日志输出。

    这样做的最大好处，就是业务层的开发不需要关心底层日志框架的实现及细节，在编码的时候也不需要考虑日后更换框架所带来的成本，这也是门面模式所带来的好处。

    请不要在你的Java代码中出现任何Log4j等日志框架的API的使用，而是应该直接使用SLF4J这种日志门面。

2.4 所有日志文件至少保存15天

所有日志文件至少保存15天，因为有些异常具备以“周”为频次发生的特点，网络运行状态、安全相关信息、系统监测、管理后台操作、用户敏感

3 单元测试

3.1 好的单元测试必须遵守 AIR 原则

单元测试在线上运行时，感觉像空气（AIR）一样并不存在，但在测试质量的保障上，却是非常关键的，好的单元测试宏观上来说，具有自动化、

3.2 单元测试应该是全自动执行的，并且非交互式的

• 测试用例通常是被定期执行的，执行过程必须完全自动化才有意义。
• 输出结果需要人工检查的测试不是一个好的单元测试。
• 单元测试中不准使用System.out来进行人肉验证，必须使用assert来验证。

3.3 单元测试是可以重复执行的，不能受到外界环境的影响

单元测试通常会被放到持续集成中，每次有代码check in时单元测试都会被执行，如果单测对外部环境（网络、服务、中间件等）有依赖，容

4 安全规约

4.1 用户敏感数据禁止直接展示，必须对展示数据进行脱敏

中国大陆个人手机号码显示为:`137****0969`，隐藏中间 4 位，防止隐私泄露，以及用户的身份证号码，银行卡号码，用户姓名等都需要进行脱

4.2 用户请求传入的任何参数必须做有效性验证

说明：忽略参数校验可能导致：

• page size 过大导致内存溢出

• 恶意 order by 导致数据库慢查询

• 缓存击穿

• 服务器端请求伪造（SSRF）

• 任意重定向

• SQL 注入，Shell 注入，反序列化注入

• 正则输入源串拒绝服务 ReDoS

5 MySQL 数据库

5.1 表明命名规范

表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间只出现数字。

数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑，MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是

• 一般以t_xxx来作为表名
• 一般以v_xxx来作为视图名称

5.2 表必备的几个字段

• 创建人：标记记录的初始创建人

• 创建时间：标记初始的创建人

• 修改人：标记修改人

• 修改时间：标记最后修改日期

• 版本号：用于统一化的乐观锁

6 工程结构

6.1 线上应用不要依赖 SNAPSHOT 版本

正式发布的类库必须先去中央仓库进行查证，使 RELEASE 版本号有延续性，且版本号不允许覆盖升级。

6.2 注意POM坐标冲突

禁止在子项目的 pom 依赖中出现相同的 GroupId，相同的 ArtifactId，但是不同的Version。

在本地调试时会使用各子项目指定的版本号，但是合并成一个 war，只能有一个版本号出现在最后的lib 目录中，曾经出现过线下调试是正确的

三、移动端代码规范

1. 文件和文件夹命名规范：

   • 文件名使用小写字母和下划线（snake_case）。
   • 文件夹名使用小写字母和下划线（snake_case）。
   • Flutter widget 的文件名应与其中定义的 widget 名称相匹配。

2. 代码格式化和布局规范：

   • 使用 2 个空格作为缩进。
   • 使用 Dart 的格式化工具（如 dartfmt）自动格式化代码。
   • 在类的成员之间使用一个空行进行分隔。
   • 在函数和方法之间使用两个空行进行分隔。

3. 导入规范：

   • 导入只应包含必要的库。
   • 导入语句应按照以下顺序进行分组：Flutter 库、第三方库、本地库。

4. 命名规范：

   • 使用驼峰命名法（camelCase）为变量和函数命名。
   • 使用大写字母开头的驼峰命名法（PascalCase）为类和枚举命名。
   • 使用小写字母开头的驼峰命名法（lowerCamelCase）为实例变量命名。
   • 使用小写字母开头的驼峰命名法（lowerCamelCase）为函数和方法命名。

5. 注释规范：

   • 使用 /// 进行文档注释。
   • 在类、函数和方法上方添加注释，描述其作用和使用方法。
   • 在代码行内使用注释，解释复杂或不明显的逻辑。

6. 状态管理：

   • 推荐使用现代的状态管理解决方案，如 Provider、Riverpod 或 BLoC。
   • 避免过度使用全局变量和可变状态。

7. Widget 构建规范：

   • 保持 widget 的构建方法简洁和单一责任原则。
   • 将复杂的 widget 拆分为小而可重用的部件。

四、代码规范原文件

前端代码规范
后端代码规范
移动端代码规范