1 | client := http.Client{ |
1 | client := http.Client{ |
1 | HttpRequest request = HttpRequest.newBuilder() |
1 | HttpClient.Builder builder = HttpClient.newBuilder() |
1 | HttpClient client = HttpClient.create().responseTimeout(Duration.ofSeconds(10)); |
1 | HttpClient client = HttpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000); |
在SDK的关键节点，比如初始化完成、连接建立或者连接断开，都可以打印日志。如果是PerRequest的日志，一般默认不会打印INFO级别的日志。
SDK应该避免仅仅打印错误日志然后忽略异常；相反，它应该提供机制让调用者能够捕获并处理异常信息。这种做法有助于保持错误处理的透明性，并允许调用者根据需要采取适当的响应措施。正如David J. Wheeler所说”Put the control in the hands of those who know how to handle the information, not those who know how to manage the computers, because encapsulated details will eventually leak out.”把控制权放到那些知道如何处理信息的人手中，而不是放在那些知道如何管理计算机的人手中，因为封装的细节最终都会暴露。
start/connect方法？#像go这样的语言，一般来说不太在意特定的时间内，某个协程是否处于阻塞等待连接的状态。而在java这样的语言，特别是在采用响应式编程模型的场景下，通常需要通过异步操作来管理连接的建立。这可以通过显式的start/connect方法来或者是异步的工厂方法来实现。
由于Influxdb 1.X的客户端已经基本处于维护状态，同时openGemini仍在不断发展中，为了能够更好地支持openGemini，如支持对接多个服务端地址、支持对接Apache
Arrow Flight协议等，社区决定开发属于openGemini自己的客户端SDK。
本文的方法假定编程语言不支持重载，如编程语言支持重载，可以对方法名进行一些优化调整。
tls相关配置可以参考TLS配置参数设计
classDiagram
class OpenGeminiClient {
+ List~Address~ addresses
+ AuthConfig authConfig // nullable, if null, means no auth
+ BatchConfig batchConfig // nullable, if null, means batch is disabled
+ timeout
+ connectTimeout
+ bool gzipEnabled
+ bool tlsEnabled
+ TlsConfig tlsConfig // language specific
+ void close()
}
class Address {
+ String host
+ int Port // in rust, it is u16
}
class AuthConfig {
+ AuthType authType // enum None, Password, Token
+ String username
+ String password
+ String token
}
class BatchConfig {
+ Duration batchInterval // must be greater than 0
+ int batchSize // must be greater than 0
}
OpenGeminiClient "1" *-- "many" Address: contains
OpenGeminiClient *-- AuthConfig: contains
OpenGeminiClient *-- BatchConfig: contains
classDiagram
class OpenGeminiClient {
+ void CreateDatabase(String database)
+ void CreateDatabaseWithRp(String database, rpConfig RpConfig)
+ String[] ShowDatabases()
+ void DropDatabase(String database)
+ void CreateRetentionPolicy(database string, rpConfig RpConfig, isDefault bool)
+ RetentionPolicy[] ShowRetentionPolicies(database string)
+ void DropRetentionPolicy(database, retentionPolicy string)
}
class RpConfig {
+ String Name
+ String Duration
+ String ShardGroupDuration
+ String IndexDuration
}
classDiagram
class OpenGeminiClient {
+ WritePoint(String database, Point point)
+ WriteBatchPoints(String database, BatchPoints batchPoints)
}
class BatchPoints {
+ List~Point~ points
+ AddPoint(Point)
}
class Point {
+ String measurement
+ Precision precision // enum, second, millisecond, microsecond, nanosecond, default is nanosecond
+ Time time // language specific
+ Map~String, String~ tags
+ Map~String, Object~ fields
+ AddTag(string, string) // init container if null
+ AddField(string, int) // init container if null
+ AddField(string, string) // init container if null
+ AddField(string, float) // init container if null
+ AddField(string, bool) // init container if null
+ SetTime(timestamp)
+ SetPrecision(type)
+ SetMeasurement(name)
}
BatchPoints "1" *-- "many" Point: contains
classDiagram
class Query {
+ String database
+ String retentionPolicy
+ String command
}
classDiagram
class QueryResult {
+ List~SeriesResult~ results
+ String error
}
class SeriesResult {
+ List~Series~ series // Series is an uncountable noun.
+ String error
}
class Series {
+ String name
+ Map~String, String~ tags
+ List~String~ columns
+ List~List~ values
}
QueryResult "1" *-- "0..*" SeriesResult: contains
SeriesResult "1" *-- "0..*" Series: contains
classDiagram
class OpenGeminiClient {
+ void ping(int index) // index selects one from multiple servers
}
使用类似InnerHttpClient的设计，将鉴权、负载均衡、重试等逻辑封装在内部，对client提供简单的接口。增强模块化和代码清晰度。
classDiagram
class InnerHttpClient {
+ void executeHttpGetByIdx(int idx, ...) // specify server index
+ void executeHttpRequestByIdx(int idx, String method, ...) // specify server index
+ void executeHttpGet(String method, ...) // load balance
+ void executeHttpRequest(String method, ...) // load balance
- void executeHttpRequestInner(String url, String method, ...) // inner method
}
graph TD
executeHttpGetByIdx --> executeHttpRequestByIdx
executeHttpRequestByIdx --> executeHttpRequestInner
executeHttpGet --> executeHttpRequest
executeHttpRequest --> executeHttpRequestInner
1 | $operation request failed, error: $error_details |
1 | $operation error resp, code: $code, body: $body |
1 | $operation failed, error: $error_details |
TLS(Transport Layer Security)是一种安全协议，用于在两个通信应用程序之间提供保密性和数据完整性。TLS是SSL(Secure Sockets Layer)的继任者。
不同的编程语言处理TLS配置的方式各有千秋, 本文针对TLS配置参数的设计进行探讨。
代码配置中，建议使用反映状态的参数名。
推荐使用方式一
方式一：
方式二：
由于Go不支持加密的私钥文件，推荐使用文件内容，而不是文件路径，避免敏感信息泄露。
Java的TLS参数基本上都是基于keystore和truststore来配置的。一般常见设计如下参数：
JavaScript可以使用标准库里的tls.SecureContextOptions
kotlin的Tls与Java相同：
推荐使用方式一
方式一
方式二
Python可以使用文件路径以及加密的私钥文件。
由于常见的Rust TLS实现不支持加密的私钥文件，推荐使用文件内容，而不是文件路径，避免敏感信息泄露。 一般常见如下设计参数:
根据Python项目的需求和特性，可以为Python的Http SDK项目选择以下命名方式：
xxx-client-python：如果这个项目只有Http SDK，没有其他协议的SDK，推荐使用这个命名方式。xxx-http-client-python：当存在其他协议的SDK时，可以使用这个命名方式，以区分不同协议的SDK。xxx-admin-python：当项目使用其他协议作为数据通道，使用HTTP协议作为管理通道时，可以使用这个命名方式。由于Python的调用方式通常是模块名.类名.方法名。
TypeScript的调用方式通常是
1 | import { ClassName } from 'moduleName'; |
根据TypeScript项目的需求和特性，可以为TypeScript的Http SDK项目选择以下命名方式：
xxx-client-ts：如果这个项目只有Http SDK，没有其他协议的SDK，推荐使用这个命名方式。在npm可以注册为”xxx”。xxx-http-client-ts：当存在其他协议的SDK时，可以使用这个命名方式，以区分不同协议的SDK。xxx-admin-ts：当项目使用其他协议作为数据通道，使用HTTP协议作为管理通道时，可以使用这个命名方式。根据Go项目的需求和特性，可以为Go的Http SDK项目选择以下命名方式：
xxx-client-go：如果这个项目只有Http SDK，没有其他协议的SDK，推荐使用这个命名方式。xxx-http-client-go：当存在其他协议的SDK时，可以使用这个命名方式，以区分不同协议的SDK。xxx-admin-go：当项目使用其他协议作为数据通道，使用HTTP协议作为管理通道时，可以使用这个命名方式。由于Go语言的调用方式是包名.结构体名.方法名，所以在设计SDK时，需要考虑包名、结构体名、方法名的设计。
以xxx业务为例，假设业务名为xxx，推荐包名也为xxx，结构体名为Client。
目录布局可以是这样子的：
1 | xxx-client-go/ |
根据Java项目的需求和特性，可以为Java的Http SDK项目选择以下命名方式：
xxx-client-java：如果这个项目只有Http SDK，没有其他协议的SDK，推荐使用这个命名方式。xxx-http-client-java：当存在其他协议的SDK时，可以使用这个命名方式，以区分不同协议的SDK。xxx-admin-java：当项目使用其他协议作为数据通道，使用HTTP协议作为管理通道时，可以使用这个命名方式。maven module命名可以叫xxx-client或者xxx-http-client，这通常取决于你的项目是否有其他协议的client，如果没有，那么推荐直接使用xxx-client。
假设包名前缀为com.xxx，module视图如下:
1 | xxx-client-java(maven artifactId: xxx-client-parent)/ |
依赖关系图:
graph TD api[xxx-client-api] common[xxx-client-common] jdk[xxx-client-jdk] okhttp[xxx-client-okhttp] reactor[xxx-client-reactor] common --> api jdk --> common okhttp --> common reactor --> common
ZooKeeper，是一个开源的分布式协调服务，不仅支持分布式选举、任务分配，还可以用于微服务的注册中心和配置中心。本文，我们将深入探讨ZooKeeper用做微服务注册中心的场景。
SpringCloud ZooKeeper遵循特定的路径结构进行服务注册
1 | /services/${spring.application.name}/${serviceId} |
示例：
1 | /services/provider-service/d87a3891-1173-45a0-bdfa-a1b60c71ef4e |
/services和/${spring.application.name}是ZooKeeper中的永久节点，/${serviceId}是临时节点，当服务下线时，ZooKeeper会自动删除该节点。
注：当微服务的最后一个实例下线时，SpringCloud ZooKeeper框架会删除/${spring.application.name}节点。
下面是一个典型的服务注册内容示例：
1 | { |
其中，address、port和uriSpec是最核心的数据。uriSpec中的parts区分了哪些内容是可变的，哪些是固定的。
一旦两个微服务都注册到了ZooKeeper，那么它们就可以通过OpenFeign互相调用了。简单的示例如下
创建SpringBoot项目，并添加spring-cloud-starter-zookeeper-discovery和spring-boot-starter-web依赖。
1 | spring: |
在启动类上添加@EnableDiscoveryClient注解。
1 | @RestController |
创建SpringBoot项目，并添加spring-cloud-starter-zookeeper-discovery、spring-cloud-starter-openfeign和spring-boot-starter-web依赖。
1 | spring: |
在启动类上添加@EnableDiscoveryClient注解。
1 | @RestController |
1 | curl localhost:8081/getHello -i |
可能有些读者乍一看觉得有点奇怪，为什么要在SpringCloud ZooKeeper中注册非Java服务呢？没有这个应用场景。
当然，这样的场景比较少，常见于大部分项目都是用SpringCloud开发，但有少部分项目因为种种原因，不得不使用其他语言开发，比如Go、Rust等。这时候，我们就需要在SpringCloud ZooKeeper中注册非Java服务了。
对于非JVM语言开发的服务，只需确保它们提供了Rest/HTTP接口并正确地注册到ZooKeeper，就可以被SpringCloud的Feign客户端所调用。
example代码组织：
1 | ├── consumer |
注：该代码的质量为demo级别，实际生产环境需要更加严谨的代码，如重连机制、超时机制、更优秀的服务ID生成算法等。
1 | package main |
调用效果
1 | curl localhost:8081/getHello -i |
1 | package main |
example代码组织：
1 | ├── Cargo.lock |
1 | use std::collections::HashMap; |
1 | use std::collections::HashMap; |
大部分软件的安装包是一个压缩包，用户需要自己解压，然后再执行安装脚本。常见的两种格式是tar.gz和zip。常见的解压执行脚本如下
1 | #!/bin/bash |
1 | #!/bin/bash |
在有些场景下，为了方便分发、安装，我们需要将多个文件和目录打包并与一个启动脚本结合。这样子就可以实现一键安装，而不需要用户自己解压文件，然后再执行启动脚本。
核心原理是，通过固定分隔符分隔脚本和压缩包部分，脚本通过分隔符将压缩包部分提取出来，然后解压，执行安装脚本，脚本不会超过固定分隔符。解压可以通过临时文件(zip)或流式解压(tar.gz)的方式实现。
1 | echo "hello zip" > temp.txt |
self_extracting.sh#以使用__ARCHIVE_BELOW__做分隔符为例，self_extracting.sh里面内容:
推荐把临时文件放在内存文件路径下，这样子可以避免磁盘IO
1 | #!/bin/bash |
将zip文件追加到self_extracting.sh文件的尾部
1 | cat temp.zip >> self_extracting.sh |
1 | echo "hello tar.gz" > temp.txt |
self_extracting.sh#以使用__ARCHIVE_BELOW__做分隔符为例，self_extracting.sh里面内容:
1 | #!/bin/bash |