Merge pull request qiniu#33 from qiniu/develop

Release v6.0.4

Author: xushiwei

CHANGELOG.md

@@ -1,5 +1,14 @@
 ## CHANGE LOG
 
+### v6.0.4
+
+2013-07-05 issue [#33](https://github.com/qiniu/sdkspec/pull/33)
+
+- 补充 ListPrefix 的标准用法
+- 增加 单元测试环境(test-env.sh) 规范
+- 增加 服务端上传（rsutil）模块规范
+
+
 ### v6.0.3
 
 2013-07-02 issue [#32](https://github.com/qiniu/sdkspec/pull/32)

IMPL.md

@@ -9,9 +9,24 @@ docs/			- 文档所在目录
 tests/  		- 单元测试目录，有的语言习惯叫 test 目录。这个建议遵循社区惯例。
 README.md		- 项目说明文档
 CHANGELOG.md	- 更新日志
+test-env.sh		- 测试环境脚本
 .travis.yml		- Travis-CI 配置文件
 ```
 
+## 单元测试环境
+
+要运行单元测试，需要先准备单元测试环境(test-env.sh)。此文件默认内容如下：
+
+```
+export QINIU_ACCESS_KEY="<Please apply your access key>"
+export QINIU_SECRET_KEY="<Dont send your secret key to anyone>"
+export QINIU_TEST_BUCKET="<Bucket that run your test cases>"
+export QINIU_TEST_DOMAIN="<Domain that binding to your test bucket>"
+```
+
+SDK 的用户需要先修改此文件，配置上相关的信息，然后 source test-env.sh，就可以正确运行所有单元测试了。test-env.sh 的内容仅限于用户通过 SDK 无法完成的一些管理性操作，比如创建空间（bucket）、关联域名（domain）等等。
+
+
 ## Travis-CI
 
 不同语言的 .travis.yml 文件略有不同，但是他们都需要有：

README.md

@@ -156,6 +156,28 @@ type ListItem struct {
 }
 ```
 
+这个 `ListPrefix` 的标准用法如下：
+
+```{go}
+import "qiniu/api/rsf"
+
+func listAll(rs rsf.Client, bucket, prefix string, limit int) {
+
+	var items []rsf.ListItem
+	var marker string
+	var err error
+	for err == nil {
+		items, marker, err = rs.ListPrefix(bucket, prefix, marker, limit)
+		for _, item := range items {
+			... // 处理item
+		}
+	}
+	if err != rsf.EOF {
+		... // 错误处理
+	}
+}
+```
+
 范围：仅在服务端使用
 
 
@@ -301,3 +323,53 @@ func (this Exif) MakeRequest(url string) (imageExifUrl string)
 
 范围：客户端和服务端
 
+
+## 服务端上传（rsutil）
+
+```{go}
+package "qiniu/api/rsutil"
+
+import (
+	"qiniu/api/rs"
+	sio "qiniu/api/io"
+	rio "qiniu/api/resumable/io"
+)
+
+// simple upload
+
+func Put(
+	c rs.Client, bucket string,
+	key string, body io.Reader, extra *sio.PutExtra) (ret sio.PutRet, err error)
+
+func PutWithoutKey(
+	c rs.Client, bucket string,
+	body io.Reader, extra *sio.PutExtra) (ret sio.PutRet, err error)
+
+func PutFile(
+	c rs.Client, bucket string,
+	key string, localFile string, extra *sio.PutExtra) (ret sio.PutRet, err error)
+
+func PutFileWithoutKey(
+	c rs.Client, bucket string,
+	localFile string, extra *sio.PutExtra) (ret sio.PutRet, err error)
+
+// resumable upload
+
+func Rput(
+	c rs.Client, bucket string,
+	key string, f io.ReaderAt, fsize int64, extra *rio.PutExtra) (ret rio.PutRet, err error)
+
+func RputWithoutKey(
+	c rs.Client, bucket string,
+	f io.ReaderAt, fsize int64, extra *rio.PutExtra) (ret rio.PutRet, err error)
+
+func RputFile(
+	c rs.Client, bucket string,
+	key string, localFile string, extra *rio.PutExtra) (ret rio.PutRet, err error)
+
+func RputFileWithoutKey(
+	c rs.Client, bucket string,
+	localFile string, extra *rio.PutExtra) (ret rio.PutRet, err error)
+```
+
+范围：仅在服务端使用。本模块仅仅是 rs + io/rio 的简单包装。