Update doc

manticorecao · Dec 22, 2016 · 32b350d · 32b350d
1 parent 436cc58
commit 32b350d
Show file tree

Hide file tree

Showing 53 changed files with 329 additions and 411 deletions.
diff --git a/sharding-jdbc-doc/README.md b/sharding-jdbc-doc/README.md
@@ -0,0 +1,2 @@
+本文档使用[hugo](http://gohugo.io/overview/introduction/)生成文档。
+同时使用主题[hugo theme learn](https://github.com/matcornic/hugo-theme-learn)来作为文档风格。
diff --git a/sharding-jdbc-doc/config.toml b/sharding-jdbc-doc/config.toml
@@ -1,24 +1,3 @@
 baseurl = "http://dangdangdotcom.github.io/sharding-jdbc/"
-languageCode = "en-us"
-title = "Sharding-JDBC"
-
-[params]
-    description = "A JDBC driver for shard databases and tables"
-    author_url = "https://github.com/dangdangdotcom"
-    project_url = "https://github.com/dangdangdotcom/sharding-jdbc"
-    project_documentation = "http://dangdangdotcom.github.io/sharding-jdbc"
-    github_project_name = "Sharding-JDBC"
-    github_user_name = "dangdangdotcom"
-
-    first_color="#f8f8f8"
-    first_border_color="#e7e7e7"
-    first_text_color="#333"
-
-    second_color="white"
-    second_text_color="#333"
-
-    header_color="#f8f8f8"
-    header_text_color="rgb(51, 51, 51)"
-
-    header_link_color="#777"
-    header_link_hover_color="rgb(51, 51, 51)"
+canonifyurls = true
+theme = "hugo-theme-learn"
diff --git a/sharding-jdbc-doc/content/post/faq.md → sharding-jdbc-doc/content/01-start/faq.md b/sharding-jdbc-doc/content/post/faq.md → sharding-jdbc-doc/content/01-start/faq.md
@@ -1,26 +1,34 @@
 +++
-date = "2016-11-23T20:30:55+08:00"
+toc = true
+date = "2016-12-06T22:38:50+08:00"
 title = "FAQ"
-weight = 0
-+++
+weight = 2
+prev = "/01-start/quick-start"
+next = "/01-start/features"
 
-## 阅读源码时为什么会出现编译错误?
++++
 
-代码使用[Lombok](https://projectlombok.org/download.html)实现极简代码。关于更多使用和安装细节，请参考官网。
+## 使用问题
 
-## 使用Spring命名空间时在网上相应地址找不到xsd?
+### 使用Spring命名空间时在网上相应地址找不到xsd?
 
 Spring命名空间使用规范并未强制要求将xsd文件部署至公网地址，只需在jar包的`META-INF\spring.schemas`配置，并在jar包中相关位置存在即可。
 
 我们并未将`http://www.dangdang.com/schema/ddframe/rdb/rdb.xsd`部署至公网，但并不影响使用。相关问题请参考Spring命名空间规范。
 
-## 异常：Cloud not resolve placeholder ... in string value ...?
+### 异常：Cloud not resolve placeholder ... in string value ...?
 
 由于inline表达式内使用Groovy语法，Groovy语法的变量占位符为`${}`,与Spring的Property占位符冲突。
 故需要在Spring的配置文件中增加
 `<context:property-placeholder location="classpath:conf/rdb/conf.properties" ignore-unresolvable="true"/>`
 
-## inline表达式返回结果出现浮点数？
+### inline表达式返回结果出现浮点数？
 
 Java的整数相除结果是整数，但是对于inline表达式中的Groovy语法则不同，整数相除结果是浮点数。
-想获得除法整数结果需要将`A/B`改为`A.intdiv(B)`
+想获得除法整数结果需要将`A/B`改为`A.intdiv(B)`
+
+## 编译源代码问题
+
+### 阅读源码时为什么会出现编译错误?
+
+代码使用[Lombok](https://projectlombok.org/download.html)实现极简代码。关于更多使用和安装细节，请参考官网。
diff --git a/sharding-jdbc-doc/content/post/features.md → ...ing-jdbc-doc/content/01-start/features.md b/sharding-jdbc-doc/content/post/features.md → ...ing-jdbc-doc/content/01-start/features.md
@@ -1,9 +1,12 @@
 +++
-date = "2016-01-08T16:14:21+08:00"
+toc = true
+date = "2016-12-06T22:38:50+08:00"
 title = "详细功能列表"
 weight = 3
+prev = "/01-start/faq"
+next = "/01-start/limitations"
+
 +++
-# 详细功能列表
 
 ## 功能性需求
 

diff --git a/sharding-jdbc-doc/content/01-start/index.md b/sharding-jdbc-doc/content/01-start/index.md
@@ -0,0 +1,38 @@
++++
+icon = "<b>1. </b>"
+date = "2016-12-02T16:06:17+08:00"
+title = "起航"
+weight = 0
+next = "/01-start/faq"
+chapter = true
+
++++
+
+# 本章导航
+
+ - 如果想快速体验`Sharding-JDBC`的强大功能，请阅读[快速上手](/01-start/quick-start)。
+ - 如果在使用中遇到什么问题，请首先在[FAQ](/01-start/faq)中寻找解决问题的答案。
+ - 想要在自己的项目中集成`Sharding-JDBC`,您一定很关心它[能做什么](/01-start/features)和[不能做什么](/01-start/limitations)。
+ - 数据库中间件一般都不会支持完全的SQL语法,在这里你能了解到[支持的SQL语法](/01-start/sql-supported)。
+ - 最后，你会关心中间件的性能情况。这里将为你我们的[性能测试结果](/01-start/stress-test)。
+
+# 简介
+
+* `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`功能灵活且全面
+ * 分片策略灵活，可支持`=`，`BETWEEN`，`IN`等多维度分片，也可支持多分片键共用。
+ * `SQL`解析功能完善，支持聚合，分组，排序，`Limit`，`OR`等查询，并且支持`Binding Table`以及笛卡尔积的表查询。
+ * 支持柔性事务(目前仅最大努力送达型)。
+ * 支持读写分离。
+ * 支持生成唯一有顺序主键
+* `Sharding-JDBC`配置多样
+ * 可支持YAML和Spring命名空间配置
+ * 灵活多样的`inline`方式
+
+
+# 整体架构图
+
+![整体架构图1](/img/architecture.png)
diff --git a/...ding-jdbc-doc/content/post/limitations.md → ...-jdbc-doc/content/01-start/limitations.md b/...ding-jdbc-doc/content/post/limitations.md → ...-jdbc-doc/content/01-start/limitations.md
@@ -1,10 +1,12 @@
 +++
-date = "2016-01-08T16:14:21+08:00"
+toc = true
+date = "2016-12-06T22:38:50+08:00"
 title = "使用限制"
-weight = 8
-+++
+weight = 4
+prev = "/01-start/features"
+next = "/01-start/sql-supported"
 
-# 使用限制
++++
 
 ## `JDBC`未支持列表
 

diff --git a/sharding-jdbc-doc/content/index/index.md → ...-jdbc-doc/content/01-start/quick-start.md b/sharding-jdbc-doc/content/index/index.md → ...-jdbc-doc/content/01-start/quick-start.md
@@ -1,70 +1,28 @@
-# 主要贡献者
++++
+toc = true
+date = "2016-12-06T22:38:50+08:00"
+title = "快速入门"
+weight = 1
+prev = "/start"
+next = "/01-start/faq"
 
-* 张亮 &nbsp;&nbsp;&nbsp;[当当](http://www.dangdang.com/) zhangliang@dangdang.com
-* 高洪涛 [当当](http://www.dangdang.com/) gaohongtao@dangdang.com
-* 曹昊 &nbsp;&nbsp;&nbsp;[当当](http://www.dangdang.com/) caohao@dangdang.com
-* 岳令 &nbsp;&nbsp;&nbsp;[当当](http://www.dangdang.com/) yueling@dangdang.com
++++
 
-# 交流与参与
+## 使用API配置
 
- - **讨论QQ群：** 532576663（不限于Sharding-JDBC，包括分布式，数据库相关以及其他互联网技术交流。由于QQ群已接近饱和，我们希望您在申请加群之前仔细阅读文档，并在加群申请中正确回答问题，以及在申请时写上您的姓名和公司名称。并且在入群后及时修改群名片。否则我们将有权拒绝您的入群申请。谢谢合作。）
- - **邮件组 sharding_jdbc@groups.163.com** ，如果在使用上需要帮助，或者疑似的bug，请发邮件到该邮件组中。发邮件之前请先阅读[FAQ](http://dangdangdotcom.github.io/sharding-jdbc/post/faq/)
- - 报告bug，提交增强功能建议和提交补丁等，请阅读[如何进行贡献](https://github.com/dangdangdotcom/sharding-jdbc/blob/master/CONTRIBUTING.md)
+### Maven安装 
 
-# 简介
-`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     | 无               |
-
-***
-
-# 整体架构图
-
-![整体架构图1](img/architecture.png)
-
-# Quick Start
-
-## 引入maven依赖
 ```xml
 <!-- 引入sharding-jdbc核心模块 -->
 <dependency>
     <groupId>com.dangdang</groupId>
     <artifactId>sharding-jdbc-core</artifactId>
-    <version>1.0.0</version>
+    <version>${sharding-jdbc.version}</version>
 </dependency>
 ```
 
 ## 规则配置
+
 `Sharding-JDBC`的分库分表通过规则配置描述，请简单浏览配置全貌：
 
 ```java
@@ -78,9 +36,10 @@ ShardingRule shardingRule = ShardingRule.builder()
 
 规则配置包括数据源配置、表规则配置、分库策略和分表策略组成。这只是最简单的配置方式，实际使用可更加灵活，如：多分片键，分片策略直接和`tableRule`绑定等。
 
->详细的规则配置请参考[用户指南](post/user_guide)
+>详细的规则配置请参考[分库分表](guide/sharding)
 
 ## 使用基于ShardingDataSource的JDBC接口
+
 通过`ShardingDataSourceFactory`工厂和规则配置对象获取`ShardingDataSource`，`ShardingDataSource`实现自`JDBC`的标准接口`DataSource`。然后可通过`DataSource`选择使用原生`JDBC`开发，或者使用`JPA`, `MyBatis`等`ORM`工具。
 以`JDBC`原生实现为例：
 
@@ -101,7 +60,19 @@ try (
 }
 ```
 
-## 使用Spring命名空间配置
+## 使用Spring
+
+### Maven安装
+
+```xml
+<!-- 引入sharding-jdbc核心模块 -->
+<dependency>
+    <groupId>com.dangdang</groupId>
+    <artifactId>sharding-jdbc-config-spring</artifactId>
+    <version>${sharding-jdbc.version}</version>
+</dependency>
+```
+### Spring命名空间
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -144,3 +115,4 @@ try (
     </rdb:data-source>
 </beans>
 ```
+>详细的规则配置请参考[Spring配置](guide/spring)
diff --git a/...ng-jdbc-doc/content/post/sql_supported.md → ...dbc-doc/content/01-start/sql-supported.md b/...ng-jdbc-doc/content/post/sql_supported.md → ...dbc-doc/content/01-start/sql-supported.md
@@ -1,10 +1,12 @@
 +++
-date = "2016-01-08T16:14:21+08:00"
+toc = true
+date = "2016-12-06T22:38:50+08:00"
 title = "SQL支持详细列表"
-weight = 9
-+++
+weight = 5
+prev = "/01-start/limitations"
+next = "/01-start/stress-test"
 
-# SQL支持详细列表
++++
 
 由于`SQL`语法灵活复杂，分布式数据库和单机数据库的查询场景又不完全相同，难免有和单机数据库不兼容的`SQL`出现。
 本文详细罗列出已明确可支持的`SQL`种类以及已明确不支持的`SQL`种类，尽量让使用者避免踩坑。
@@ -36,6 +38,7 @@ SELECT select_expr [, select_expr ...] FROM table_reference [, table_reference .
 ```
 
 #### select_expr
+
 ```sql
 * | 
 COLUMN_NAME [AS] [alias] | 
@@ -44,6 +47,7 @@ COUNT(* | COLUMN_NAME | alias) [AS] [alias]
 ```
 
 #### table_reference
+
 ```sql
 tbl_name [AS] alias] [index_hint_list] | 
 table_reference ([INNER] | {LEFT|RIGHT} [OUTER]) JOIN table_factor [JOIN ON conditional_expr | USING (column_list)] | 

diff --git a/...ding-jdbc-doc/content/post/stress_test.md → ...-jdbc-doc/content/01-start/stress-test.md b/...ding-jdbc-doc/content/post/stress_test.md → ...-jdbc-doc/content/01-start/stress-test.md
@@ -1,10 +1,13 @@
 +++
-date = "2016-01-08T16:14:21+08:00"
-title = "压力测试报告"
-weight = 10
-chart = true
+toc = true
+date = "2016-12-06T22:38:50+08:00"
+title = "性能测试报告"
+weight = 6
+prev = "/01-start/sql-supported"
+next = "/02-guide"
+
 +++
-# 压力测试报告
+
 ## 测试目的
 对`Sharding-JDBC`进行性能测试，客观、公正评估系统的性能，目的有三:
 
@@ -25,7 +28,7 @@ chart = true
 | 数据表行数   | 1000万                   | 1000万                   |
 ## 网络拓扑
 
-![网络拓扑图](../../img/stress_test_arch.png)
+![网络拓扑图](/img/stress_test_arch.png)
 ## 单库情况下Sharding-JDBC与JDBC性能对比
 测试结论：
 
@@ -87,3 +90,18 @@ chart = true
 经过8个小时的疲劳测试，jvm的堆大约占用不到600MB的内存，且使用量比较稳定。没有发生Full GC。
 <canvas id="fatigueTest" width="400" height="150"></canvas>
 
+<script src="//cdn.bootcss.com/moment.js/2.11.1/moment.min.js"></script>
+<script src="//cdn.bootcss.com/Chart.js/2.0.0-beta2/Chart.min.js"></script>
+<script src="/data/chart.js"></script>
+<script>
+    $("canvas").each(function(){
+        var data =  chartData[$(this).attr("id")];
+        $(data.datasets).each(function(index, obj){
+            $.extend(obj, charStyle[index])
+        });
+        new Chart(this.getContext("2d"),{
+            type: 'line',
+            data: data
+        });
+    })
+</script>
diff --git a/sharding-jdbc-doc/content/post/concepts.md → ...ing-jdbc-doc/content/02-guide/concepts.md b/sharding-jdbc-doc/content/post/concepts.md → ...ing-jdbc-doc/content/02-guide/concepts.md
@@ -1,7 +1,11 @@
 +++
-date = "2016-03-03T16:14:21+08:00"
+toc = true
+date = "2016-12-06T22:38:50+08:00"
 title = "核心概念"
-weight = 4
+weight = 1
+prev = "/02-guide"
+next = "/02-guide/sharding"
+
 +++
 
 本文介绍`Sharding-JDBC`包含的一些核心概念。