松果生活alpha冲刺项目规划

松果生活alpha冲刺项目规划

 

一、alpha冲刺任务

 

（一）后端数据库部分

• 完成数据库的搭建和数据表的构建
• 编写相关的增删改查代码
• 与后台界面进行数据交互
• 部署到服务器上进行数据交互测验

 

（二）后端后台部分

• 完成大致页面的搭建
• 与数据库进行数据交互测验

 

（三）安卓端部分

• 完成登录界面的构建
• 完成主页以及主要视图fragment的搭建
• 做好数据的持久化存储
• 与后台界面进行数据交互测验

 

（四）iOS端部分

• 完成登录界面的构建
• 完成主页以及部分视图的搭建
• 与后台界面进行数据交互测验

 

（五）产品文档部分

• 优化软件设计说明书
• 完成会议记录
• 完成alpha冲刺的冲刺随笔
• 完成相关的代码规范

 

二、冲刺计划

 

工作内容	完成时间	负责人员
编写alpha冲刺项目规划文档以及代码规范	冲刺1前	彭陈浩
第零次会议	冲刺1前	全体成员
后台的数据库、表构建以及初步部署	冲刺1	吴章权、胡世鑫、包鹏飞、龚俊鹏、胡锦浩
登录界面搭建并测试相关api	冲刺1	彭陈浩、李昊朋
后台用户、文章等页面的搭建	冲刺1	赖晓辉、朱鸿昊
数据库的增删改查以及与后台的数据交互	冲刺2-6	吴章权、胡世鑫、包鹏飞、龚俊鹏、胡锦浩、赖晓辉、朱鸿昊
移动端基础界面的完善，发布功能的构建	冲刺2-6	彭陈浩、李昊朋
移动端与后台的数据交互测试	冲刺7	彭陈浩、李昊朋、朱鸿昊、赖晓辉
数据库的相关测试以及排查bug	冲刺7	吴章权、胡世鑫、包鹏飞、龚俊鹏、胡锦浩
移动端与后台单元测试	冲刺8-9	全体成员
测试用例文档编写以及测试评述	冲刺10	全体成员
文档编写	冲刺10后	全体成员

 

三、编程规约

 

（一）命名规范

1. 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
3. 类名使用UpperCamelCase风格，必须遵从驼峰形式。
4. 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。
5. 常量命名全部大写，单词间用下划线隔开。（Fujian等地名除外）
6. 中括号是数组类型的一部分，数组定义如下：String[] args;
7. POJO类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。
8. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词，包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
9. 如果使用到了设计模式，建议在类名中体现出具体模式。
10. 接口类中的方法和属性不要加任何修饰符号（public也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
11. 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test结尾。
12. 杜绝完全不规范的缩写，避免望文不知义。
13. 为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
14. 如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。

 

（二）代码格式

1. 任何二目、三目运算符的左右两边都需要加一个空格

2. 在if/else/for/while/do语句中必须使用大括号，即使只有一行代码，避免使用下面的形式：if (condition) statements; 保留字与括号之间都必须加空格。

3. 尽量少用else， if-else的方式可以改写成：

   if(condition){
       ...
       return obj;
   }
   

4. 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

   • 左大括号前不换行。
   • 左大括号后换行。
   • 右大括号前换行。
   • 右大括号后还有else等代码则不换行；表示终止右大括号后必须换行。

5. 方法间必须要空行，方法参数在定义和传入时，多个参数逗号后边必须加空格。

6. 缩进使用四个空格而不是用Tab缩进，在IDE中设置Tab的格式为四个空格。左小括号和字符之间不出现空格 ； 同样，右小括号和字符之间也不出现空格。

7. 单行字符数限制不超过120个，超出需要换行，换行时遵循如下原则：

   • 第二行相对第一行缩进 4个空格，从第三行开始，不再继续缩进，参考示例。
   • 运算符与下文一起换行。
   • 方法调用的点符号与下文一起换行。
   • 在多个参数超长，逗号后进行换行。
   • 在括号前不要换行

8. 函数最大行数100行，一个方法内只实现一个功能，方便阅读，尽量减少使用分叉，提高代码覆盖率

9. IDE 的 text file encoding 设置为 UTF-8;IDE中文件的换行符使用 Unix 格式，不要使用 Windows 格式。

 

（三）常量定义

1. 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中。
2. long或者Long初始赋值时，必须使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。
3. 不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。如：缓存相关的常量放在类：CacheConsts下；系统配置相关的常量放在类：ConfigConsts下。
4. 如果变量值仅在一个范围内变化用Enum类。如果还带有名称之外的延伸属性，必须使用Enum类，下面正例中的数字就是延伸信息，表示星期几。

 

（四）OOP规约

1. 避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
2. 所有的覆写方法，必须加@ Override 注解。
3. 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object 。说明：可变参数必须放置在参数列表的最后。
4. 外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@ Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
5. 不能使用过时的类或方法。
6. Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
7. 所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。
8. 序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败 ； 如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
9. 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
10. 使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
11. 循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展

 

（五）集合处理

1. 关于 hashCode 和 equals 的处理，遵循如下规则：

   • 只要重写 equals ，就必须重写 hashCode 。
   • 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
   • 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals

2. ArrayList 的 subList 结果不可强转成 ArrayList ，否则会抛出 ClassCastException异常

3. 使用集合转数组的方法，必须使用集合的 toArray(T[] array) ，传入的是类型完全一样的数组，大小就是 list.size()

4. 使用工具类 Arrays.asList() 把数组转换成集合时，不能使用其修改集合相关的方法，它的 add / remove / clear 方法会抛出 UnsupportedOperationException 异常

5. 不要在 foreach 循环里进行元素的 remove / add 操作。 remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁

6. 在 JDK 7 版本及以上， Comparator 要满足如下三个条件，不然 Arrays.sort ，Collections.sort 会报 IllegalArgumentException 异常。

   • x，y 的比较结果和 y，x 的比较结果相反。
     阿里巴巴 Java 开发手册
     —— 禁止用于商业用途，违者必究—— 11 /35
   • x > y ， y > z ，则 x > z 。
   • x = y ，则 x ， z 比较结果和 y ， z 比较结果相同。

7. 集合初始化时，指定集合初始值大小。

 

（六）并发处理

1. 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
2. 创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
3. 线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
4. 线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
5. SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为static ，必须加锁，或者使用 DateUtils 工具类。
6. 高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁 ； 能锁区块，就不要锁整个方法体 ； 能用对象锁，就不要用类锁。
7. 对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
8. 并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。
9. 多线程并行处理定时任务时， Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。

 

（七）注释规约

1. 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。注释的双斜线与注释内容之间有且仅有一个空格。
2. 所有的抽象方法 （ 包括接口中的方法 ） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
3. 所有的类都必须添加创建者和创建日期
4. 所有的枚举类型字段必须要有注释，说明每个数据项的用途
5. 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可

 

（八）其他规约

1. 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
2. 后台输送给页面的变量必须加 $!{var} ——中间的感叹号。
3. 注意 Math . random() 这个方法返回是 double 类型，注意取值的范围 0≤ x <1 （ 能够取到零值，注意除零异常 ） ，如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法。
4. 获取当前毫秒数 System . currentTimeMillis(); 而不是 new Date() . getTime();
5. 不要在视图模板中加入任何复杂的逻辑

 

四、异常日志

 

（一）异常处理

1. Java 类库中定义的一类 RuntimeException 可以通过预先检查进行规避，而不应该通过 catch 来处理。
2. 异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。
3. 对大段代码进行 try - catch ，这是不负责任的表现。 catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。
4. 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。
5. 有 try 块放到了事务代码中， catch 异常后，如果需要回滚事务，一定要注意手动回滚事务。
6. finally 块必须对资源对象、流对象进行关闭，有异常也要做 try - catch 。
7. 不能在 finally 块中使用 return ， finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。
8. 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。

 

（二）日志处理

1. 应用中不可直接使用日志系统 （Log 4 j 、 Logback） 中的 API ，而应依赖使用日志框架SLF 4 J 中的 API ，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
2. 日志文件推荐至少保存 15 天，因为有些异常具备以“周”为频次发生的特点。
3. 对 trace / debug / info 级别的日志输出，必须使用条件输出形式或者使用占位符的方式。
4. 谨慎地记录日志。生产环境禁止输出 debug 日志 ； 有选择地输出 info 日志 ； 如果使用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志。

 

五、单元测试

1. 好的单元测试必须遵守 AIR 原则。A： Automatic （自动化）I： Independent （独立性）R： Repeatable （可重复）
2. 单元测试应该是全自动执行的，并且非交互式的。测试框架通常是定期执行的，执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测试中不准使用 System.out 来进行人肉验证，必须使用 assert 来验证。
3. 保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。
4. 单元测试的基本目标：语句覆盖率达到 70% ；核心模块的语句覆盖率和分支覆盖率都要达到 100%
5. 核心业务、核心应用、核心模块的增量代码确保单元测试通过。
6. 对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单测粒度至多是类级别，一般是方法级别。
7. 单元测试是可以重复执行的，不能受到外界环境的影响。

 

六、安全规约

1. 隶属于用户个人的页面或者功能必须进行权限控制校验。
2. 用户敏感数据禁止直接展示，必须对展示数据进行脱敏。
3. 用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入，禁止字符串拼接 SQL 访问数据库。
4. 用户请求传入的任何参数必须做有效性验证。
5. 禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。
6. 表单、 AJAX 提交必须执行 CSRF 安全过滤。
7. 在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损。
8. 发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。

 

七、MySQL数据库规约

1. 表达是与否概念的字段，必须使用 is _ xxx 的方式命名，数据类型是 unsigned tinyint（ 1 表示是，0 表示否 ） 。
2. 表名、字段名必须使用小写字母或数字 ， 禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。
3. 表名不使用复数名词。
4. 禁用保留字，如 desc 、 range 、 match 、 delayed 等，请参考 MySQL 官方保留字。
5. 小数类型为 decimal ，禁止使用 float 和 double 。
6. 如果存储的字符串长度几乎相等，使用 char 定长字符串类型。
7. varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
8. 表必备三字段： id , gmt_create , gmt_modified。 id 必为主键，类型为 unsigned bigint 、单表时自增、步长为 1。gmt_create,gmt_modified 的类型均为 date_time 类型，前者现在时表示主动创建，后者过去分词表示被动更新。
9. 业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。
10. 超过三个表禁止 join 。需要 join 的字段，数据类型必须绝对一致 ； 多表关联查询时，保证被关联的字段需要有索引。
11. 在 varchar 字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度即可。
12. 页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。
13. 不要使用 count( 列名 ) 或 count( 常量 ) 来替代 count()，count() 是 SQL 92 定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。
14. 当某一列的值全是 NULL 时， count(col) 的返回结果为 0，但 sum(col) 的返回结果为NULL ，因此使用 sum() 时需注意 NPE 问题。
15. 在代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。
16. 不得使用外键与级联，一切外键概念必须在应用层解决。
17. 禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。
18. 数据订正时，删除和修改记录时，要先 select ，避免出现误删除，确认无误才能执行更新语句。