README.zh-Hans.md

MYDICTIONARY 在线服务

English Version

这个仓库是 MYDICTIONARY （版本 <= v3.0.0）的一个依赖。

1. 简介

这是一个为MYDICTIONARY提供带有缓存支持的在线服务的模块。

2. 缓存

该模块能够缓存从在线服务获得的查询结果。这会显著增加联网查询的速度。

2.1. 数据结构

type ItemStruct struct {
	QueryString  string   `json:"queryString"`
	Word         string   `json:"word"`
	Definition   []string `json:"definition"`
	Status       string   `json:"status"`
	CreationTime int64    `json:"creationTime"`
}

ItemStruct是一个结构体，包含下列成员：

• QueryString指示了查询字符串。
• Word指示了词汇。
• Definition指示了释义。
• Status指示了状态。
• CreationTime是一个UNIX时间戳，它指示了本缓存项的创建时间。

type CacheStruct struct {
	path         string
	shelfLifeDay int64
	Content      []ItemStruct `json:"content"`
}

CacheStruct是一个结构体。

它具有一个公开的成员Content用于存放所有的缓存项。

2.2. 成员函数

func (cache *CacheStruct) Read(path string, shelfLifeDay int64) (err error)

这个函数用于从被path指定的JSON文件中读取缓存，同时将shelfLifeDay设定为所有缓存项的保存期限（天）。

• 如果path指定的文件不存在，那么创建之。
• 如果shelfLifeDay为0，那么缓存永不过期。

在读取缓存之后，每个缓存项会被检查以确定是否过期（由缓存项的CreationTime、缓存的shelfLifeDay和当前时间共同决定）。随后，所有过期的缓存项将被移除。

func (cache *CacheStruct) Query(queryString string) (item ItemStruct, err error)

这个函数用于在缓存中搜索queryString。

func (cache *CacheStruct) Add(item ItemStruct)

这个函数用于添加item到缓存。

func (cache *CacheStruct) Write()

这个函数用于将缓存写回JSON文件。

3. 在线服务

3.1. 接口

所有在线服务都应当满足以下接口。

type ServiceInterface interface {
	GetServiceName() string
	GetCache() *CacheStruct
	Query(vocabulary4mydictionary.VocabularyAskStruct) vocabulary4mydictionary.VocabularyAnswerStruct
}

2.2.1. GetServiceName

func (service *ServiceInterface) GetServiceName()

该函数返回在线服务的名称。

3.1.2. GetCache

func (service *ServiceInterface) GetCache()

该函数返回在线服务缓存的指针。

3.1.3. Query

func (service *ServiceInterface) Query(vocabularyAsk vocabulary4mydictionary.VocabularyAskStruct) (vocabularyAnswer vocabulary4mydictionary.VocabularyAnswerStruct)

该函数用来查询词条。

3.2. 目前支持的在线服务

3.2.1. 必应词典

http://cn.bing.com/dict/

type BingDictionaryStruct struct {
	cache CacheStruct
}

3.2.2. 金山词霸-柯林斯词典

http://www.iciba.com/

type IcibaCollinsStruct struct {
	cache CacheStruct
}

3.2.3. 韦氏词典

https://www.merriam-webster.com/

type MerriamWebsterStruct struct {
	cache CacheStruct
}

3.3. 创建自定义在线服务

• 在本包内新建一个".go"文件。
• 复制下列代码到这个新文件（推荐使用goquery来获取网页内容）。

package service4mydictionary

import (
	"net/url"
	"time"

	"github.com/PuerkitoBio/goquery"
	"github.com/zzc-tongji/vocabulary4mydictionary"
)

const serviceName = "Service"

//
// NOTE:
// 1. Change "Service" above to your service name.
// 2. Rename all "ServiceStruct" below in this file.
// 3. Delete this note in your service.
//

// ServiceStruct : service struct
type ServiceStruct struct {
	cache CacheStruct
}

// GetServiceName : get service name
func (service *ServiceStruct) GetServiceName() (value string) {
	value = serviceName
	return
}

// GetCache : get cache
func (service *ServiceStruct) GetCache() (cache *CacheStruct) {
	cache = &service.cache
	return
}

// Query : query vocabulary
func (service *ServiceStruct) Query(vocabularyAsk vocabulary4mydictionary.VocabularyAskStruct) (vocabularyAnswer vocabulary4mydictionary.VocabularyAnswerStruct) {
	var (
		err         error
		queryString string
		item        CacheItemStruct
	)
	// set
	vocabularyAnswer.SourceName = serviceName
	vocabularyAnswer.Location.TableType = vocabulary4mydictionary.Online
	vocabularyAnswer.Location.TableIndex = -1
	vocabularyAnswer.Location.ItemIndex = -1
	// query cache
	queryString = url.QueryEscape(vocabularyAsk.Word)
	item, err = service.cache.Query(queryString)
	if err == nil {
		goto SET
	}
	// query online
	//
	// NOTE:
	// 1. Add your code here.
	// 2. If success, "item.Status" should be "vocabulary4mydictionary.Basic";
	//    else, set "item.Status" as your debug information and jump to label 'ADD' immidiately.
	// 3. To help you debug this function,
	//    set "online.debug" in file "mydictionary.setting.json" as "true".
	//    At this time, MYDICTIONARY will show off the debug information.
	// 4. Set "online.debug" in file "mydictionary.setting.json" as "false"
	//    to let MYDICTIONARY will hide the debug information
	// 5. Delete this note in your service.
	//
ADD:
	// add to cache
	item.QueryString = queryString
	item.CreationTime = time.Now().Unix()
	service.cache.Add(item)
SET:
	// set
	vocabularyAnswer.Word = item.Word
	vocabularyAnswer.Definition = item.Definition
	vocabularyAnswer.Status = item.Status
	return
}

• 根据NOTE开头的注释，修改上述文件。
• 根据NOTE开头的注释，更新MYDICTIONARY中的setting.go文件。
• 使用推送请求来提交你的修改，帮助优化MYDICTIONARY（可选）。

4. 其他

• 所以代码文件是用Atom编写的。
• 所有".md"文件是用Typora编写的。
• 所有".md"文件的风格是Github Flavored Markdown。
• 各行以LF（Linux）结尾。