Büyükelçi düzeniAmbassador pattern

Bir tüketici hizmeti veya uygulaması adına ağ istekleri gönderen yardımcı hizmetler oluşturur.Create helper services that send network requests on behalf of a consumer service or application. Bir büyükelçi hizmeti, istemciyle birlikte bulunan bir işlem dışı proxy olarak düşünülebilir.An ambassador service can be thought of as an out-of-process proxy that is co-located with the client.

Bu düzen; izleme, günlüğe kaydetme, yönlendirme, güvenlik (TLS gibi) ve dayanıklılık düzenleri gibi ortak istemci bağlantısı görevlerinin dilden bağımsız bir şekilde boşaltılması için kullanışlı olabilir.This pattern can be useful for offloading common client connectivity tasks such as monitoring, logging, routing, security (such as TLS), and resiliency patterns in a language agnostic way. Genellikle eski uygulamaların veya değiştirilmesi zor olan diğer uygulamaların ağ yeteneklerinin genişletilmesi için kullanılır.It is often used with legacy applications, or other applications that are difficult to modify, in order to extend their networking capabilities. Özel bir ekibin bu özellikleri uygulamasına da imkan tanıyabilir.It can also enable a specialized team to implement those features.

Bağlam ve sorunContext and problem

Dayanıklı bulut tabanlı uygulamalar gerektiren özellikleri gibi devre kesme, yönlendirme, ölçüm ve izleme ve ağ ile ilgili yapılandırma güncelleştirmelerini gerçekleştirebilme imkanı.Resilient cloud-based applications require features such as circuit breaking, routing, metering and monitoring, and the ability to make network-related configuration updates. Eski uygulamaların veya mevcut kod kitaplıklarının kodu artık korunmadığından veya geliştirme ekibi tarafından kolayca değiştirilemediğinden, bunların güncelleştirilerek bu özelliklerin eklenmesi zor olabilir veya mümkün olmayabilir.It may be difficult or impossible to update legacy applications or existing code libraries to add these features, because the code is no longer maintained or can't be easily modified by the development team.

Ağ çağrıları da bağlantı, kimlik doğrulama ve yetkilendirme için önemli ölçüde yapılandırma gerekebilir.Network calls may also require substantial configuration for connection, authentication, and authorization. Bu çağrılar birden çok dil ve çerçeve kullanılarak oluşturulmuş birden çok uygulamada kullanılıyorsa, çağrıların bu örneklerin her biri için yapılandırılmış olması gerekir.If these calls are used across multiple applications, built using multiple languages and frameworks, the calls must be configured for each of these instances. Ayrıca, ağ ve güvenlik işlevselliğinin kuruluşunuzdaki merkezi bir ekip tarafından yönetilmesi gerekebilir.In addition, network and security functionality may need to be managed by a central team within your organization. Kod tabanı büyükse, bu ekibin aşina olmadığı uygulama kodunu güncelleştirmesi riskli olabilir.With a large code base, it can be risky for that team to update application code they aren't familiar with.

ÇözümSolution

İstemci çerçevelerini ve kitaplıkları uygulamanız ile dış hizmetler arasında proxy görevi gören bir dış işleme yerleştirin.Put client frameworks and libraries into an external process that acts as a proxy between your application and external services. Yönlendirme, dayanıklılık, güvenlik özellikleri üzerinde denetimi mümkün kılmanın yanı sıra konakla ilgili erişim kısıtlamalarından kaçınmak için proxy’yi uygulamanızla aynı konak ortamında dağıtın.Deploy the proxy on the same host environment as your application to allow control over routing, resiliency, security features, and to avoid any host-related access restrictions. Ayrıca, büyükelçi düzenini kullanarak izlemeyi standartlaştırıp genişletebilirsiniz.You can also use the ambassador pattern to standardize and extend instrumentation. Proxy tarafından gecikme veya kaynak kullanımı gibi performans ölçümleri izlenebilir ve bu izleme işlemleri uygulamayla aynı konak ortamında gerçekleşir.The proxy can monitor performance metrics such as latency or resource usage, and this monitoring happens in the same host environment as the application.

Büyükelçi düzeni diyagramı

Büyükelçiye boşaltılan özellikler, uygulamadan bağımsız olarak yönetilebilir.Features that are offloaded to the ambassador can be managed independently of the application. Büyükelçiyi uygulamanın eski işlevselliğini etkilemeden güncelleştirip değiştirebilirsiniz.You can update and modify the ambassador without disturbing the application's legacy functionality. Ayrıca, bağımsız ve özel ekiplerin büyükelçiye taşınan güvenlik, ağ veya kimlik doğrulama özelliklerini uygulamasına veya bunların bakımını yapmasına imkan tanır.It also allows for separate, specialized teams to implement and maintain security, networking, or authentication features that have been moved to the ambassador.

Büyükelçi Hizmetleri olarak dağıtılabilir bir sepet kullanan bir uygulamanın veya hizmetin yaşam döngüsüne eşlik edecek.Ambassador services can be deployed as a sidecar to accompany the lifecycle of a consuming application or service. Alternatif olarak, bir büyükelçi ortak bir konak üzerindeki birden çok ayrı işlem tarafından paylaşılıyorsa bir daemon veya Windows hizmeti olarak dağıtılabilir.Alternatively, if an ambassador is shared by multiple separate processes on a common host, it can be deployed as a daemon or Windows service. Büyükelçiyi kullanan hizmet kapsayıcılıysa, büyükelçinin aynı konaktaki ayrı bir kapsayıcı olarak oluşturulması ve iletişim için uygun bağlantıların yapılandırılması gerekir.If the consuming service is containerized, the ambassador should be created as a separate container on the same host, with the appropriate links configured for communication.

Sorunlar ve dikkat edilmesi gerekenlerIssues and considerations

  • Proxy biraz gecikme yükü ekler.The proxy adds some latency overhead. Doğrudan uygulama tarafından çağrılan bir istemci kitaplığının daha iyi bir yaklaşım olup olmayacağını göz önünde bulundurun.Consider whether a client library, invoked directly by the application, is a better approach.
  • Proxy’ye genelleştirilmiş özellikler eklemenin olası etkisini göz önünde bulundurun.Consider the possible impact of including generalized features in the proxy. Örneğin, büyükelçi yeniden deneme işlemlerini gerçekleştirebilir, ancak tüm işlemler bir kere etkili olmuyorsa bu yöntem güvenli olmayabilir.For example, the ambassador could handle retries, but that might not be safe unless all operations are idempotent.
  • Hem istemciden proxy’ye hem de ters yönde bazı bağlam bilgilerinin geçirilmesine imkan tanıyan bir mekanizmayı göz önünde bulundurun.Consider a mechanism to allow the client to pass some context to the proxy, as well as back to the client. Örneğin, yeniden denemeyi geri çevirmeye yönelik HTTP isteği üst bilgileri ekleyin veya en fazla yeniden deneme sayısını belirtin.For example, include HTTP request headers to opt out of retry or specify the maximum number of times to retry.
  • Proxy’yi nasıl paketleyip dağıtacağınızı göz önünde bulundurun.Consider how you will package and deploy the proxy.
  • Tüm istemciler için tek bir paylaşılan örnek mi yoksa her istemci için bir örnek mi kullanacağınızı göz önünde bulundurun.Consider whether to use a single shared instance for all clients or an instance for each client.

Bu düzenin kullanılacağı durumlarWhen to use this pattern

Bu düzeni aşağıdaki durumlarda kullanın:Use this pattern when you:

  • Birden çok dil veya çerçeve için ortak bir dizi istemci bağlantı özelliği oluşturmanızı gerektiren durumlar.Need to build a common set of client connectivity features for multiple languages or frameworks.
  • Çapraz kesme bağlantı konularını geliştiricilere veya diğer daha özel ekiplere devretmenizi gerektiren durumlar.Need to offload cross-cutting client connectivity concerns to infrastructure developers or other more specialized teams.
  • Eski veya değiştirilmesi zor bir uygulamada bulut veya küme bağlantı gereksinimlerini desteklemenizi gerektiren durumlar.Need to support cloud or cluster connectivity requirements in a legacy application or an application that is difficult to modify.

Bu düzen şu durumlarda uygun olmayabilir:This pattern may not be suitable:

  • Ağ isteği gecikme süresinin kritik olduğu durumlar.When network request latency is critical. Proxy eklenmesi, yükün az da olsa artmasına yol açar ve bazı durumlarda uygulama bundan etkilenebilir.A proxy will introduce some overhead, although minimal, and in some cases this may affect the application.
  • İstemci bağlantı özelliklerinin tek bir dil tarafından kullanıldığı durumlar.When client connectivity features are consumed by a single language. Bu durumda, geliştirme ekiplerine bir paket olarak dağıtılan bir istemci kitaplığı daha iyi bir seçenek olabilir.In that case, a better option might be a client library that is distributed to the development teams as a package.
  • Bağlantı özelliklerinin genelleştirilemediği ve istemci uygulaması ile daha derin tümleştirme gerektirdiği durumlar.When connectivity features cannot be generalized and require deeper integration with the client application.

ÖrnekExample

Aşağıdaki diyagramda, büyükelçi proxy’si üzerinden uzak bir hizmete istek gerçekleştiren bir uygulama gösterilmiştir.The following diagram shows an application making a request to a remote service via an ambassador proxy. Büyükelçi tarafından yönlendirme, devre kesme ve günlüğe kaydetme özellikleri sağlanır.The ambassador provides routing, circuit breaking, and logging. Büyükelçi, uzak hizmete çağrı yapar ve yanıtı istemci uygulamasına döndürür:It calls the remote service and then returns the response to the client application:

Büyükelçi düzeni örneği