For #197: initial version for 00-overview chapter.

01050c24 · haocao · d5da3bab · 01050c24 · 01050c24 · 01050c24
4 changed file
--- a/sharding-jdbc-doc/content/00-overview/contribution.md
+++ b/sharding-jdbc-doc/content/00-overview/contribution.md
+# 如何成为贡献者？
+
+您可以报告bug，提交一个新的功能增强建议或者直接对以上内容提交改进补丁。
+
+## 报告bug
+
+本章节介绍如何提交一个bug。
+
+### 报告一个新bug之前
+
+ - 确定在最新版本中该bug存在。我们将不会持续维护所有的发布版本，所有的修改仅根据当前版本。
+ - 确认该bug是可以复现的。请尽量提供完整的重现步骤。
+ - 请确定这不是一个重复的bug。
+   查看[Issue Page](https://github.com/dangdangdotcom/sharding-jdbc/issues)列表，搜索您要提交的bug是否已经被报告过。
+
+### 如何提交一个有质量的bug
+
+请在[Issue Page](https://github.com/dangdangdotcom/sharding-jdbc/issues)页面中提交bug。
+
+ - 使用一个清晰并有描述性的标题来定义bug。
+ - 详细的描述复现bug的步骤。包括您使用的SQL，配置情况，预计产生的结果，实际产生的结果。并附加详细的TRACE日志。
+ - 如果程序抛出异常，请附加完整的堆栈日志。
+ - 如有可能，请附上屏幕截图或动态的GIF图，这些图片能帮助演示整个问题的产生过程。
+ - 如果涉及性能问题，请附加上CPU，内存或网络磁盘IO的Profile截图。
+ - 说明适用的版本，只有release版本的bug才可以提交，并且应该是当前最新版本。
+ - 说明适用的操作系统，及其版本。
+ - 使用bug标签(Label)来标记这个issue。
+
+以下是bug的Markdown模板，请按照该模板填写issue。
+
+```
+[问题简单描述]
+
+**问题复现步骤:**
+
+1. [第一步]
+2. [第二步]
+3. [其他步骤...]
+
+**期望的表现:**
+
+[在这里描述期望的表现]
+
+**观察到的表现:**
+
+[在这里描述观察到的表现]
+
+**屏幕截图和动态GIF图**
+
+![复现步骤的屏幕截图和动态GIF图](图片的url)
+
+**Sharding-JDBC版本:** [输入Sharding-JDBC的版本]
+**操作系统及版本:** [输入操作系统及版本]
+
+```
+
+## 提交功能增强建议
+
+本章节介绍如何提交一个功能增强建议。
+
+### 提交一个功能增强建议之前
+ 
+ - 请先检查[详细功能列表](http://dangdangdotcom.github.io/sharding-jdbc/post/features/)。
+ - 请确定这不是一个重复的功能增强建议。
+   查看[Issue Page](https://github.com/dangdangdotcom/sharding-jdbc/issues)列表，搜索您要提交的功能增强建议是否已经被提交过。
+
+### 如何提交一个好的功能增强建议
+
+请在[Issue Page](https://github.com/dangdangdotcom/sharding-jdbc/issues)页面中提交功能增强建议。
+
+ - 使用一个清晰并有描述性的标题来定义增强建议。
+ - 详细描述增强功能的行为模式。
+ - 解释说明为什么该功能是对大多数用户是有用的。新功能应该具有广泛的适用性。
+ - 如有可能，可以列出其他数据库中间已经具备的类似功能。商用与开源软件均可。
+ - 使用enhancement标签(Label)来标记这个issue。
+
+以下是功能增强建议的Markdown模板，请按照该模板填写issue。
+
+```
+[简单的建议描述]
+
+**建议的新功能行为**
+
+[描述新功能应表现的行为模式]
+
+**为什么这个新功能是对大多数用户有用的**
+
+[解释这个功能为什么对大多数用户是有用的]
+
+[列出其他的数据库中间件是否包含该功能，且如何实现的]
+
+```
+
+## 贡献补丁(patch)
+
+本文档帮助贡献者搭建开发环境并贡献代码，示例和文档。
+
+### 编译代码
+
+Sharding-JDBC的代码编译需要[Maven](http://maven.apache.org/)，请保证IDE中正确配置了它。
+代码用到的所有依赖完全都可以从公网下载，请根据自身的网络情况选择合理的镜像。
+
+代码使用了[Lombok](https://projectlombok.org/download.html)来生成类属性的访问方法，构造器等。
+故请以上从链接内容来获取适合您的IDE的解决方法。
+
+### 文档生成
+
+文档使用博客生成引擎[HUGO](https://gohugo.io/)，请根据文档安装环境。
+文档全部在sharding-jdbc/sharding-jdbc-doc/content/post目录中。
+
+### 贡献方法
+
+请按照下面的步骤贡献代码，示例和文档。
+
+ - 所有的问题与新功能请使用[Issue Page](https://github.com/dangdangdotcom/sharding-jdbc/issues)进行管理。
+ - 任何人想要开发任何功能，请先回复该功能所关联的Issue，表明您当前正在这个Issue上工作。
+   并在回复的时候为自己设置一个deadline，并添加的回复内容中。
+ - 在核心贡献者找到一个导师(shepherd)，导师会在设计与功能实现上给予即时的反馈。
+   如果您没有熟悉的架构师，请向__sharding_jdbc@groups.163.com__发送邮件。
+ - 您应该新建一个分支来开始您的工作，分支的名字为功能名称/issueId。
+   例如，您想完成一个SQL解析(parser)功能中 __Issue 111__，那么您的branch名字应为 __parser/111__。
+   功能名称与导师讨论后确定。
+ - 完成后，发送一个pull request到dangdangdotcom/sharding-jdbc，
+   接着导师做CodeReview，然后他会与您讨论一些细节（包括设计，实现，性能等）。当团队中所有人员对本次修改满意后，导师会将提交合并到master分支。
+ - 最后，恭喜您已经成为了Sharding-JDBC的官方贡献者！
+
+### 开发理念
+
+ - 用心写代码，提炼真正的非功能性需求。
+ - 代码整洁干净到极致, 请参见《重构》和《代码整洁之道》。
+ - 极简代码, 高度复用，无重复代码和配置。
+ - 代码应在同一抽象层级。
+ - 修改功能时多考虑影响面, 不可留下没修改完全的部分。
+ - 只有一个需求时，不需扩展性。两个类似需求时, 再提炼扩展性。
+
+### 开发行为规范
+
+ - 提交之前先确定模块的测试套件，并使用测试覆盖率工具检查覆盖率不能低于master分支的覆盖率。
+ - 使用Checkstyle检查代码, 违反验证规则的需要有特殊理由。模板位置在sharding-jdbc/src/resources/dd_checks.xml。
+ - 执行mvn clean install可以测试和编译通过。
+ - 及时删除无用代码。
+ 
+### 编码规范
+
+ - 写代码之前看一下系统已有的代码, 保持风格和使用方式一致。
+ - 变量命名要有意义, 如果方法只有唯一的返回值, 使用result命名返回值. 循环中使用each命名循环变量, map中使用entry代替each。
+ - 嵌套循环尽量提成方法。
+ - 优先使用卫语句。
+ - 配置文件使用驼峰命名, 文件名首字母小写。
+ - 类和方法的访问权限控制为最小, 例如: 可以设为包私有的就不用public。
+ - 方法所用到的私有方法应紧跟着该方法, 如果有多个私有方法, 书写私有方法应与私有方法在原方法的出现顺序相同。
+ - 优先使用guava而非apache commons, 如：优先使用Strings而非StringUtils。
+ - 优先使用lombok代替构造器, get, set, log方法。
+ - 使用linux换行符。
+ - 缩进（包含空行）和上一行保持一致。
+ - 不应有无意义的空行。
+ - 方法入参和返回值不允许为null，如有特殊情况需注释说明。
+ - 需要注释解释的代码尽量提成小方法，用方法名称解释，注释应只包含javadoc和todo，fixme等。
+ - 禁止使用static import。
+ - 不需要公开的类放入internal包，包中类尽量包私有。
+ - 日志一律使用英文。
+ - 使用annotation获取spring的业务bean。
+ - 如果模块中有公用的切入点，应在模块一级路径创建pointcut包。
+ - 属性配置项需要添加到各个模块的常量枚举中。
+
+### 单元测试规范
+
+ - 测试代码和生产代码需遵守相同代码规范。
+ - 如无特殊理由, 测试需全覆盖。
+ - 准备环境的代码和测试代码分离。
+ - 单数据断言, 应使用assertTrue, assertFalse, assertNull, assertNotNull。
+ - 多数据断言, 应使用assertThat。
+ - 精确断言, 尽量不使用not, containsString断言。
+ - 调用业务方法的变量, 应命名为actualXXX, 期望值应命名为expectedXXX。
+ - 只有junit assertXXX, hamcrest, mocktio相关可以使用static import。
\ No newline at end of file
--- a/sharding-jdbc-doc/content/00-overview/index.md
+++ b/sharding-jdbc-doc/content/00-overview/index.md
+++
+icon = "<b>0. </b>"
+date = "2017-04-12T16:06:17+08:00"
+title = "概览"
+weight = 0
+prev = "/03-develop/roadmap"
+next = "/00-overview/intro"
+chapter = true
+
+++
+
+# 概述
+
+Sharding-JDBC是当当应用框架ddframe中，关系型数据库模块dd-rdb中分离出来的数据库水平扩展框架，即透明化数据库分库分表访问。Sharding-JDBC继dubbox和Elastic-Job之后，是ddframe系列开源的第三个产品。
+
+Sharding-JDBC定位为轻量级java框架，使用客户端直连数据库，以jar包形式提供服务，未使用中间层，无需额外部署，无其他依赖，DBA也无需改变原有的运维方式，可理解为增强版的JDBC驱动，旧代码迁移成本几乎为零。
+
+[![Maven Status](https://maven-badges.herokuapp.com/maven-central/com.dangdang/sharding-jdbc/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.dangdang/sharding-jdbc)
+[![Build Status](https://secure.travis-ci.org/dangdangdotcom/sharding-jdbc.png?branch=master)](https://travis-ci.org/dangdangdotcom/sharding-jdbc)
+[![Coverage Status](https://coveralls.io/repos/dangdangdotcom/sharding-jdbc/badge.svg?branch=master&service=github)](https://coveralls.io/github/dangdangdotcom/sharding-jdbc?branch=master)
+[![GitHub release](https://img.shields.io/github/release/dangdangdotcom/sharding-jdbc.svg)](https://github.com/dangdangdotcom/sharding-jdbc/releases)
+[![Hex.pm](http://dangdangdotcom.github.io/elastic-job/img/license.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
+
+# 功能列表
+
+## 1. 分库分表
+* SQL解析功能完善，支持聚合，分组，排序，LIMIT，OR等查询，并且支持级联表以及笛卡尔积的表查询
+* 支持内、外连接查询
+* 分片策略灵活，可支持=，BETWEEN，IN等多维度分片，也可支持多分片键共用，以及自定义分片策略
+* 基于Hint的强制分库分表路由
+
+## 2. 读写分离
+* 一主多从的读写分离配置，可配合分库分表使用
+* 基于Hint的强制主库路由
+
+## 3. 分布式事务
+* 最大努力送达型事务
+* TCC型事务(TBD)
+
+## 4. 兼容性
+* 可适用于任何基于java的ORM框架，如：JPA, Hibernate, Mybatis, Spring JDBC Template或直接使用JDBC
+* 可基于任何第三方的数据库连接池，如：DBCP, C3P0, BoneCP, Druid等
+* 理论上可支持任意实现JDBC规范的数据库。虽然目前仅支持MySQL，但已有支持Oracle，SQLServer，DB2等数据库的计划
+
+## 5. 灵活多样的配置
+* Java
+* Spring命名空间
+* YAML
+* Inline表达式
+
+## 6. 分布式生成全局主键
+* 统一的分布式基于时间序列的ID生成器
+
+# 第三方文档
+* 2017-03 [开源中国高手问答：高手问答第144期—轻量级数据库中间层 Sharding-JDBC 深度解析](https://www.oschina.net/question/2720166_2233456)
+* 2016-06 [InfoQ文章：Sharding-JDBC 1.3.0发布——支持读写分离](http://www.infoq.com/cn/news/2016/06/sharding-jdbc-130)
+* 2016-02 [CSDN文章：解读分库分表中间件Sharding-JDBC](http://geek.csdn.net/news/detail/55513)
+* 2016-01 [InfoQ新闻：当当开源sharding-jdbc，轻量级数据库分库分表中间件](http://www.infoq.com/cn/news/2016/01/sharding-jdbc-dangdang)
+
+# 交流与参与
+
+ - **讨论QQ群：** 532576663（不限于Sharding-JDBC，包括分布式，数据库相关以及其他互联网技术交流。由于QQ群已接近饱和，我们希望您在申请加群之前仔细阅读文档，并在加群申请中正确回答问题，以及在申请时写上您的姓名和公司名称。并且在入群后及时修改群名片。否则我们将有权拒绝您的入群申请。谢谢合作。）
+ - **邮件组 sharding_jdbc@groups.163.com** ，如果在使用上需要帮助，或者疑似的bug，请发邮件到该邮件组中。发邮件之前请先阅读[FAQ](/01-start/faq)。
+ - 报告确定的bug，提交增强功能建议和提交补丁等，请阅读[如何进行贡献](/00-overview/contribution)。
+ 
+ **使用Sharding-JDBC的公司如果方便请留下公司+网址** https://github.com/dangdangdotcom/sharding-jdbc/issues/234
+  
+# 采用公司（统计中）
--- a/sharding-jdbc-doc/content/00-overview/intro.md
+++ b/sharding-jdbc-doc/content/00-overview/intro.md
+++
+toc = true
+date = "2016-12-06T22:38:50+08:00"
+title = "简介"
+weight = 1
+prev = "/00-overview"
+next = "/00-overview/release-notes"
+
+++
+
+Sharding-JDBC直接封装JDBC API，可以理解为增强版的JDBC驱动，旧代码迁移成本几乎为零：
+
+* 可适用于任何基于java的ORM框架，如：JPA, Hibernate, Mybatis, Spring JDBC Template或直接使用JDBC。
+* 可基于任何第三方的数据库连接池，如：DBCP, C3P0, BoneCP, Druid等。
+* 理论上可支持任意实现JDBC规范的数据库。虽然目前仅支持MySQL，但已有支持Oracle，SQLServer，DB2等数据库的计划。
+
+Sharding-JDBC定位为轻量级java框架，使用客户端直连数据库，以jar包形式提供服务，未使用中间层，无需额外部署，无其他依赖，DBA也无需改变原有的运维方式。SQL解析使用Druid解析器，是目前性能最高的SQL解析器。
+
+Sharding-JDBC功能灵活且全面：
+
+* 分片策略灵活，可支持=，BETWEEN，IN等多维度分片，也可支持多分片键共用。
+* SQL解析功能完善，支持聚合，分组，排序，Limit，OR等查询，并且支持Binding Table以及笛卡尔积的表查询。
+* 支持柔性事务(目前仅最大努力送达型)。
+* 支持读写分离。
+* 支持分布式生成全局主键。
+
+Sharding-JDBC配置多样：
+
+* 可支持YAML和Spring命名空间配置
+* 灵活多样的inline方式
+
+***
+
+以下是常见的分库分表产品和Sharding-JDBC的对比：
+
+| 功能          | Cobar         | Cobar-client  | TDDL        | Sharding-JDBC  |
+| ------------- |:-------------:| -------------:| -----------:|---------------:|
+| 分库          | 有            | 有             | 未开源      | 有              |
+| 分表          | 无            | 无             | 未开源      | 有              |
+| 中间层        | 是            | 否             | 否          | 否              |
+| ORM支持       | 任意          | 仅MyBatis      | 任意        | 任意            |
+| 数据库支持     | 仅MySQL       | 任意           | 任意        | 任意            |
+| 异构语言       | 可           | 仅Java          | 仅Java     | 仅Java          |
+| 外部依赖       | 无           | 无              | Diamond    | 无              |
+
+***
+
+# 整体架构图
+
+![整体架构图](http://dangdangdotcom.github.io/sharding-jdbc/img/architecture.png)
+
+![柔性事务-最大努力送达型](http://dangdangdotcom.github.io/sharding-jdbc/img/architecture-soft-transaction-bed.png)
+
+# 快速入门
+
+## 引入maven依赖
+
+```xml
+<!-- 引入sharding-jdbc核心模块 -->
+<dependency>
+    <groupId>com.dangdang</groupId>
+    <artifactId>sharding-jdbc-core</artifactId>
+    <version>${latest.release.version}</version>
+</dependency>
+```
+
+## 规则配置
+Sharding-JDBC的分库分表通过规则配置描述，请简单浏览配置全貌：
+
+```java
+ShardingRule shardingRule = ShardingRule.builder()
+        .dataSourceRule(dataSourceRule)
+        .tableRules(tableRuleList)
+        .databaseShardingStrategy(new DatabaseShardingStrategy("sharding_column", new XXXShardingAlgorithm()))
+        .tableShardingStrategy(new TableShardingStrategy("sharding_column", new XXXShardingAlgorithm())))
+        .build();
+```
+
+规则配置包括数据源配置、表规则配置、分库策略和分表策略组成。这只是最简单的配置方式，实际使用可更加灵活，如：多分片键，分片策略直接和tableRule绑定等。
+
+## 使用原生JDBC接口
+通过ShardingDataSourceFactory工厂和规则配置对象获取ShardingDataSource，ShardingDataSource实现自JDBC的标准接口DataSource。然后可通过DataSource选择使用原生JDBC开发，或者使用JPA, MyBatis等ORM工具。
+以JDBC原生实现为例：
+
+```java
+DataSource dataSource = ShardingDataSourceFactory.createDataSource(shardingRule);
+String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
+try (
+        Connection conn = dataSource.getConnection();
+        PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
+    preparedStatement.setInt(1, 10);
+    preparedStatement.setInt(2, 1001);
+    try (ResultSet rs = preparedStatement.executeQuery()) {
+        while(rs.next()) {
+            System.out.println(rs.getInt(1));
+            System.out.println(rs.getInt(2));
+        }
+    }
+}
+```
+
+## 使用Spring命名空间配置
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xmlns:context="http://www.springframework.org/schema/context"
+    xmlns:rdb="http://www.dangdang.com/schema/ddframe/rdb" 
+    xsi:schemaLocation="http://www.springframework.org/schema/beans 
+                        http://www.springframework.org/schema/beans/spring-beans.xsd
+                        http://www.springframework.org/schema/context 
+                        http://www.springframework.org/schema/context/spring-context.xsd 
+                        http://www.dangdang.com/schema/ddframe/rdb 
+                        http://www.dangdang.com/schema/ddframe/rdb/rdb.xsd 
+                        ">
+    <context:property-placeholder location="classpath:conf/rdb/conf.properties" ignore-unresolvable="true"/>
+    
+    <bean id="dbtbl_0" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
+        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
+        <property name="url" value="jdbc:mysql://localhost:3306/dbtbl_0"/>
+        <property name="username" value="root"/>
+        <property name="password" value=""/>
+    </bean>
+    <bean id="dbtbl_1" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
+        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
+        <property name="url" value="jdbc:mysql://localhost:3306/dbtbl_1"/>
+        <property name="username" value="root"/>
+        <property name="password" value=""/>
+    </bean>
+
+    <rdb:strategy id="orderTableStrategy" sharding-columns="order_id" algorithm-expression="t_order_${order_id.longValue() % 4}"/>
+    <rdb:strategy id="orderItemTableStrategy" sharding-columns="order_id" algorithm-expression="t_order_item_${order_id.longValue() % 4}"/>
+    <rdb:data-source id="shardingDataSource">
+        <rdb:sharding-rule data-sources="dbtbl_0,dbtbl_1">
+            <rdb:table-rules>
+                <rdb:table-rule logic-table="t_order" actual-tables="t_order_${0..3}" table-strategy="orderTableStrategy"/>
+                <rdb:table-rule logic-table="t_order_item" actual-tables="t_order_item_${0..3}" table-strategy="orderItemTableStrategy"/>
+            </rdb:table-rules>
+            <rdb:default-database-strategy sharding-columns="none" algorithm-class="com.dangdang.ddframe.rdb.sharding.api.strategy.database.NoneDatabaseShardingAlgorithm"/>
+        </rdb:sharding-rule>
+    </rdb:data-source>
+</beans>
+```
--- a/sharding-jdbc-doc/content/03-community/release-notes.md
+++ b/sharding-jdbc-doc/content/03-community/release-notes.md
@@ -3,10 +3,11 @@ toc = true
 date = "2016-12-06T22:38:50+08:00"
 title = "Release Note"
 weight = 2
-prev = "/03-community/architecture"
-next = "/03-community/directory-structure"
+prev = "/00-overview/intro"
+next = "/01-start/index"

 +++
+
 ## 1.4.2

 ### 功能提升
@@ -177,7 +178,7 @@ next = "/03-community/directory-structure"
 1. [ISSUE #16](https://github.com/dangdangdotcom/sharding-jdbc/issues/16) 改造多线程执行模型
 1. [ISSUE #18](https://github.com/dangdangdotcom/sharding-jdbc/issues/18) 查询Count时，使用getObject()取数会报异常
 1. [ISSUE #19](https://github.com/dangdangdotcom/sharding-jdbc/issues/19) sum和avg函数，不加别名不执行merger，加了空指针异常
-1. [ISSUE #38](https://github.com/dangdangdotcom/sharding-jdbc/issues/38) JPA与Sharding-JDBC的兼容问题。JPA会自动增加SELECT的列别名，导致ORDER BY只能通过别名，而非列名称获取ResultSet的数据。
+1. [ISSUE #38](https://github.com/dangdangdotcom/sharding-jdbc/issues/38) JPA与Sharding-JDBC的兼容问题。JPA会自动增加SELECT的列别名，导致ORDER BY只能通过别名，而非列名称获取ResultSet的数据

 ## 1.0.0
-1. 初始版本。
+1. 初始版本