Orcs!

这是一个正在进行中的作品！

用于在单一代码库内构建和部署微服务的工具。

• 用法
• 术语
• 配置文件

用法

初始化命令

• orcs init {project}: 创建一个新的项目
• orcs init {project} -t {template}: 创建一个新的项目
• orcs new service {service}: 创建一个新的服务
• orcs new service {service} -t {template}: 创建一个新的服务
• orcs new recipe {recipe}: 创建一个新的食谱

运行命令

• orcs run all: 运行所有阶段的所有服务
• orcs run {stage}: 运行特定阶段的所有服务
• orcs run all {service}: 运行特定服务的所有阶段
• orcs run {stage} {service}: 运行特定服务的特定阶段

参数存储命令

• orcs get {parameter}: 获取参数值
• orcs get-file {parameter} {filename}: 获取工件文件
• orcs set {parameter} {value}: 设置参数值
• orcs set-file {parameter} {filename}: 存储工件文件

术语

操作

操作是指针对特定服务和阶段的执行命令列表。

阶段还支持检查操作，这些操作旨在快速执行并在阶段应再次运行时返回错误。

参数

参数是服务在执行其操作后提供的一个值。

参数可以是简单值，例如API端点URL，也可以是文件，如压缩库等。

项目

项目代表包含多个服务、食谱等的仓库。

食谱

食谱是一系列默认的操作，可以由服务使用。

例如，如果许多服务使用相同的编程语言，您可能希望为使用该语言的linting、构建和测试服务创建一个食谱。

服务

服务代表微服务或其他微服务使用的共享库。

服务之间可以相互依赖，这些依赖关系可能根据阶段而变化。例如，可能同时构建两个微服务，但一个需要等待另一个更新。

阶段

阶段是项目整个工作流程中的一个步骤。

简单的流程通常由两个阶段组成：构建和部署。在服务内部，阶段将包括一系列操作，以执行与该阶段相关的所需操作。例如，构建库或部署微服务。

阶段可以相互依赖，从而允许复杂的流程。

在完整运行过程中，阶段也可以被跳过，例如如果是清理阶段。

配置文件

项目文件

项目文件是项目根目录中的orcs.toml文件，由三个主要部分组成：全局、envs和阶段。

• 全局部分定义了可以在所有阶段和环境之间使用的参数。
• envs部分定义了只能在环境本身内部使用的参数。
• 阶段部分定义了阶段、阶段之间的依赖关系、阶段内使用的参数值以及它支持的环境（可以是空）。

[global.params]
# Global parameters accessible in all services and stages

project = "my-project"

##################
#  Environments  #
##################

# This section contains environment-specific parameters.
# These may override values from the global parameters. 

[envs.dev]
params.is-prod = "false"

[envs.prod]
params.is-prod = "true"

##################
#     Stages     #
##################

[stages.build]
# Leaving the section empty will create a stage but let all internal properties
# empty. This means no dependencies, parameters or environments.

[stages.deploy]
# Stages may depend on other stages
depends_on = ["build"]

# Stages may also have parameter values within the project file.
# Stage parameters will override environment parameters.
params.target = "linux"

# If a stage supports environments, it should refer to the list of environments
# it supports. Not all stages have to support all environments
envs = ["dev", "prod"]

服务文件

服务文件是特定服务文件夹中的orcs.toml文件，包含有关服务的所有说明和元数据。

# An optional description about what the service does
# This can contain multiple lines.
description = """API to returns a string backwards

## Usage

..."""

# List of maintainers for that service
maintainers = [
  "John Doe <[email protected]>"
]

# An optional page where people can find more information about the service.
homepage = "https://wiki.company.example/my-service"

# List of recipes used by that service.
# Recipes will be resolved in order, with the first recipe to set actions for a
# stage taking over.
recipes = [
  "python"
]

##################
#     Stages     #
##################

# Stages contains the instruction to run a specific stage for that service.
# Stages can also list which services they depend on. This will ensure that the
# dependencies are run first, and also grant access to the parameters/artifacts
# provided by those dependencies.

[stages.build]
depends_on = []

# Actions
# You can provide a list of actions either with an array of strings or with a
# multi-line string.
actions = [
  "echo Hello from $ORCS_SERVICE",
  # You can use 'orcs set' and 'orcs get' within a list of actions to set and
  # retrieve parameter values.
  "orcs set my-parameter:value"
]

# Check
# Checks are meant to run fast and tell if the stage/service should be run
# prior to another, dependent stage/service combo.
#
# If you try to run a stage for a dependency of this service and this returns
# a non-zero (aka false) value, the run will fail.
#
# If you run this stage/service combo and wants to skip the actions, you should
# rely on checking this in the actions section instead.
#
# By default, this is set to "false".
check = "false"

[stages.deploy]
depends_on = []

# Actions
# An explicit 'false' value (without quotes) will disable the actions entirely
# and prevent recipes from overwiting these values.
# If you want a recipe to overwrite this, you can set it to an empty value
# (either empty string or empty array).
actions = false

# Check
check = "false"

食谱文件

食谱文件是项目rcp文件夹中的TOML文件，仅支持阶段部分。在这些部分中，您可以定义常见用例的默认操作和检查。

仅支持食谱文件中的操作和检查。

[stages.build]
actions = [
  "echo Hello from a recipe"
]

check = [
  "echo Check if the stage needs to be built"
]

[stages.deploy]
actions = [
  "echo Hello from a recipe"
]